@walkeros/core 4.8.1-next-1792019907609 → 4.8.2

package/dist/index.d.mts

@@ -325,6 +325,18 @@ interface ObserveServer {
     sample?: number;
 }
 type Observe = ObserveWeb | ObserveServer;
+/** Where a web arm finds its credential: the page, from `@walkeros/web-core`. */
+interface ObserveSlot {
+    /** The URL credential if present, else the stored one; null when absent. */
+    read(): {
+        raw: string;
+        fromUrl: boolean;
+    } | null;
+    /** Persist `raw`; when it came from the URL, strip it from the address bar. */
+    keep(raw: string, fromUrl: boolean): void;
+    /** Clear the stored credential only while it still equals `raw`. */
+    clear(raw: string): void;
+}
 /** Claims carried by a parsed `obsw_` web credential. */
 interface ObserveCredential {
     /** Project binding. Must match the value baked into the host bundle. */
@@ -413,10 +425,16 @@ interface FlowState {
     inEvent?: unknown;
     /** Outbound walker event/payload for this hop. Only populated when level === 'trace' or includeOut === true. */
     outEvent?: unknown;
-    /** Error info when phase === 'error'. */
+    /**
+     * Error info when phase === 'error'. A delivery failure also carries its
+     * failure `code`, whether a retry can help and the HTTP `status`.
+     */
     error?: {
         name?: string;
         message: string;
+        code?: string;
+        retryable?: boolean;
+        status?: number;
     };
     /** The mapping rule that matched, when one matched. */
     mappingKey?: string;
@@ -431,7 +449,7 @@ interface FlowState {
     /** For phase === 'flush', the batch size + entry index. */
     batch?: FlowStateBatch;
     /** Discriminator when phase === 'skip'. */
-    skipReason?: 'consent' | 'cache_hit' | 'sampled_out' | 'disabled' | 'dropped' | 'unknown';
+    skipReason?: 'consent' | 'cache_hit' | 'sampled_out' | 'disabled' | 'dropped' | 'ignored' | 'unknown';
     /** Free-form metadata: store key/value, cached: true, etc. */
     meta?: Record<string, unknown>;
 }
@@ -445,6 +463,48 @@ interface FlowState {
  */
 type ObserverFn = (state: FlowState) => void;
 
+/** What a failure line is about: the step, the cause code and the HTTP status. */
+interface CauseKey {
+    step: string;
+    code: string;
+    status?: number;
+}
+/** Where cause lines go; `Logger.Instance` fits, and so does a test recorder. */
+interface CauseLogger {
+    error(message: string, context: Record<string, unknown>): void;
+    warn(message: string, context: Record<string, unknown>): void;
+}
+/**
+ * One line per cause: the first occurrence of a key is logged at once,
+ * repeats within the window are counted and printed as `suppressed: <n>`
+ * with the next line of that key or at `flush`.
+ */
+interface CauseLog {
+    report(key: CauseKey, message: string, context: Record<string, unknown>, level?: 'error' | 'warn'): void;
+    /** Print the pending `suppressed` counts (server shutdown). */
+    flush(): void;
+    /** Number of keys held. */
+    size(): number;
+}
+interface CauseLogOptions {
+    windowMs?: number;
+    maxKeys?: number;
+    now?: () => number;
+}
+/**
+ * Creates the cause log of one collector. Rate limit per (step, code,
+ * status): one line per window, repeats counted. At most `maxKeys` keys are
+ * held; a key beyond the cap is logged on every occurrence, never dropped
+ * and never suppressed. No timers: windows are checked on report.
+ */
+declare function createCauseLog(logger: CauseLogger, options?: CauseLogOptions): CauseLog;
+/**
+ * The one entry for every failure line: through the collector's cause log,
+ * or, without one (a hand-built collector), one filtered line through
+ * `logger`.
+ */
+declare function reportCause(collector: Instance$6 | undefined, logger: CauseLogger, key: CauseKey, message: string, context: Record<string, unknown>, level?: 'error' | 'warn'): void;
+
 /** Identifies which kind of step a stepId belongs to. */
 type StepKind = 'collector' | 'source' | 'transformer' | 'destination' | 'store';
 /**
@@ -509,6 +569,14 @@ interface Config$6 {
      * destination backfill. Overflow drops oldest (FIFO). Default 1000.
      */
     queueMax?: number;
+    /**
+     * What a destination does with an event whose required consent is not
+     * granted: `'queue'` (default) keeps it in the destination's `queuePush`
+     * until consent is granted; `'skip'` skips it (counted in
+     * `status.destinations[id].skipped`, a DEBUG line), for a server collector
+     * that never receives a later grant for an event's own consent.
+     */
+    consentDenied?: 'queue' | 'skip';
     /** Flow name; keys this flow's entry in event.source.release and the observer flowId. */
     name?: string;
     /** Config release id stamped into event.source.release for this flow. */
@@ -547,11 +615,14 @@ interface InitConfig extends Partial<Config$6> {
     /**
      * Observation session connect config, wired by `startFlow` before the run
      * command. The server form attaches a telemetry poster directly from its
-     * config trio; the web form attaches only when an `elbObserve` credential
-     * is present (URL param or storage slot) and its binding matches. Purely
-     * advisory: nothing on this path can affect event processing.
+     * config trio; the web form reads its credential through `slot`
+     * (`pageObserveSlot()` from `@walkeros/web-core`) and attaches only when
+     * one is present and its binding matches. Purely advisory: nothing on this
+     * path can affect event processing.
      */
-    observe?: Observe;
+    observe?: (ObserveWeb & {
+        slot: ObserveSlot;
+    }) | ObserveServer;
     /**
      * Caller-supplied observers, added verbatim to `collector.observers` by
      * `startFlow`. Escape hatch for custom emit targets; same advisory
@@ -658,6 +729,11 @@ interface SourceStatus {
 interface DestinationStatus {
     count: number;
     failed: number;
+    /**
+     * Events deliberately not sent: a consent-denied event under
+     * `consentDenied: 'skip'`, or an event a mapping rule `ignore`s.
+     */
+    skipped?: number;
     lastAt?: number;
     duration: number;
     /** Current size of the destination's queuePush buffer (point-in-time). */
@@ -684,7 +760,7 @@ interface Transformers$1 {
 interface Stores$1 {
     [id: string]: Instance$1;
 }
-type CommandType = 'action' | 'config' | 'consent' | 'context' | 'destination' | 'elb' | 'globals' | 'hook' | 'init' | 'link' | 'run' | 'user' | 'walker' | string;
+type CommandType = 'action' | 'config' | 'consent' | 'context' | 'destination' | 'elb' | 'flush' | 'globals' | 'hook' | 'init' | 'link' | 'run' | 'shutdown' | 'user' | 'walker' | string;
 /**
  * Options passed to collector.push() from sources.
  * NOT a Context - just push metadata.
@@ -775,6 +851,12 @@ interface Instance$6 {
      */
     observeLevel?: () => 'off' | 'standard' | 'trace';
     logger: Instance$3;
+    /**
+     * The collector's one cause log: every failure line goes through it, one
+     * line per (step, cause code, status) per minute. Set by `startFlow`;
+     * optional only so hand-built test collectors keep compiling.
+     */
+    causeLog?: CauseLog;
     on: OnConfig;
     queue: Events;
     /**
@@ -1007,6 +1089,66 @@ declare namespace lifecycle {
   export type { lifecycle_DestroyContext as DestroyContext, lifecycle_DestroyFn as DestroyFn, lifecycle_LifecycleContext as LifecycleContext, lifecycle_SetupFn as SetupFn };
 }
 
+/**
+ * Options of a {@link StepError}: the failure code, and what decides whether
+ * a retry can help (`status`, an explicit `retryable`).
+ */
+interface StepErrorOptions {
+    code: string;
+    status?: number;
+    retryable?: boolean;
+    /** The response body: kept on the error, never in its message or a log line. */
+    body?: unknown;
+    cause?: unknown;
+}
+/** Why a push failed, as a push result and the logs carry it. Never a body. */
+type FailureReason = {
+    code: string;
+    message: string;
+    retryable: boolean;
+    status?: number;
+};
+/** Why an event waits instead of being delivered now. */
+type QueueReason = 'consent' | 'batch' | 'held';
+type QueuedReason = {
+    code: QueueReason;
+    message: string;
+};
+/**
+ * The error a step throws when it cannot do its work: a missing setting
+ * (`config`), a refused request (`transport` with its `status`), a vendor
+ * that is not there. The collector reads `code` and `retryable` instead of
+ * the message.
+ */
+declare class StepError extends Error {
+    code: string;
+    status?: number;
+    retryable: boolean;
+    body?: unknown;
+    cause?: unknown;
+    constructor(message: string, options: StepErrorOptions);
+}
+/**
+ * Runs one vendor or SDK call, sync or async, and waits for it. A
+ * `StepError` it throws passes through unchanged (the step's own code wins);
+ * anything else becomes a `StepError` with `code` and `message`, the
+ * original kept as `cause` and never in the message, which a vendor can fill
+ * with the values it was sent.
+ */
+declare function stepCall<T>(call: () => T | PromiseLike<T>, code: string, message: string): Promise<Awaited<T>>;
+/**
+ * The reason of any thrown value: a `StepError` keeps its code, status and
+ * `retryable`; anything else is a `transport` failure. The message is capped
+ * at 300 characters; the body never leaves the error.
+ */
+declare function toFailureReason(err: unknown): FailureReason;
+/**
+ * A network error's message with its cause code (`ECONNREFUSED`, `ENOTFOUND`),
+ * which runtimes keep on `cause` (Node's fetch says only `fetch failed`): the
+ * code only, never the cause's message, which carries addresses and URLs.
+ */
+declare function networkErrorMessage(error: unknown): string;
+
 /**
  * Package-internal type helpers. Not re-exported from `types/index.ts`.
  */
@@ -1159,9 +1301,20 @@ type Credentials$2<T extends TypesGeneric$3 = Types$4> = T['credentials'];
  * Inference helper: Extract Types from Instance
  */
 type TypesOf$3<I> = I extends Instance$5<infer T> ? T : never;
+/**
+ * An event waiting in a destination's `queuePush`, with why it waits:
+ * `consent` (its required consent is not granted) or `held` (a state
+ * delivery to the destination is running or failed). An entry seeded from
+ * the collector's replay buffer has no reason yet. The entry object keeps its
+ * identity across drain and requeue; the event inside is copied.
+ */
+interface Queued {
+    event: Event;
+    reason?: 'consent' | 'held';
+}
 interface Instance$5<T extends TypesGeneric$3 = Types$4> {
     config: Config$5<T>;
-    queuePush?: Events;
+    queuePush?: Queued[];
     queueOn?: Array<{
         type: Types$2;
         data?: unknown;
@@ -1347,7 +1500,7 @@ interface PushBatchContext<T extends TypesGeneric$3 = Types$4> extends Context$5
     ingest: Ingest;
     rule?: Rule<Mapping$1<T>>;
 }
-type InitFn$2<T extends TypesGeneric$3 = Types$4> = (context: Context$5<T>) => PromiseOrValue<void | false | Config$5<T>>;
+type InitFn$2<T extends TypesGeneric$3 = Types$4> = (context: Context$5<T>) => PromiseOrValue<void | Config$5<T>>;
 type PushFn<T extends TypesGeneric$3 = Types$4> = (event: Event, context: PushContext<T>) => PromiseOrValue<void | unknown>;
 /**
  * Per-row outcome for a single failed batch entry.
@@ -1426,20 +1579,35 @@ interface BatchRegistry<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.
+         * drain, `walker flush` and by tests for deterministic flushing without
+         * timer advancement. Resolves after the underlying `pushBatch` settles,
+         * with what that flush did (nothing when the batch was empty).
          */
-        flush: () => Promise<void>;
+        flush: () => Promise<BatchFlushOutcome | void>;
     };
 }
+/**
+ * What one batch flush did: entries delivered and failed, and the reason of
+ * a failure when any entry failed.
+ */
+interface BatchFlushOutcome {
+    delivered: number;
+    failed: number;
+    reason?: FailureReason;
+}
 type Data = Property | undefined | Array<Property | undefined>;
 interface Ref {
     type: string;
     data?: unknown;
     error?: unknown;
+    /**
+     * Why the destination did not deliver now: a `FailureReason` under
+     * `failed`, a `QueuedReason` under `queued`.
+     */
+    reason?: FailureReason | QueuedReason;
 }
 type Push$1 = {
-    queuePush?: Events;
+    queuePush?: Queued[];
     error?: unknown;
 };
 type DLQ = Array<[Event, unknown]>;
@@ -1466,6 +1634,7 @@ declare function getDestination<T extends TypesGeneric$3 = Types$4>(collector: {
 type destination_Batch<Mapping> = Batch<Mapping>;
 type destination_BatchEntry<Mapping = unknown> = BatchEntry<Mapping>;
 type destination_BatchFailure = BatchFailure;
+type destination_BatchFlushOutcome = BatchFlushOutcome;
 type destination_BatchOptions = BatchOptions;
 type destination_BatchOutcome = BatchOutcome;
 type destination_BatchRegistry<Mapping> = BatchRegistry<Mapping>;
@@ -1484,10 +1653,11 @@ type destination_PushContext<T extends TypesGeneric$3 = Types$4> = PushContext<T
 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_Queued = Queued;
 type destination_Ref = Ref;
 declare const destination_getDestination: typeof getDestination;
 declare namespace destination {
-  export { type BaseEnv$3 as BaseEnv, type destination_Batch as Batch, type destination_BatchEntry as BatchEntry, type destination_BatchFailure as BatchFailure, type destination_BatchOptions as BatchOptions, type destination_BatchOutcome as BatchOutcome, type destination_BatchRegistry as BatchRegistry, type destination_BreakerOptions as BreakerOptions, type Code$1 as Code, type Config$5 as Config, type Context$5 as Context, type Credentials$2 as Credentials, type destination_DLQ as DLQ, type destination_Data as Data, type destination_Destinations as Destinations, type Env$3 as Env, type destination_EnvObserve as EnvObserve, type Init$3 as Init, type destination_InitDestinationEntry as InitDestinationEntry, type destination_InitDestinations as InitDestinations, type destination_InitDestinationsOf as InitDestinationsOf, 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 };
+  export { type BaseEnv$3 as BaseEnv, type destination_Batch as Batch, type destination_BatchEntry as BatchEntry, type destination_BatchFailure as BatchFailure, type destination_BatchFlushOutcome as BatchFlushOutcome, type destination_BatchOptions as BatchOptions, type destination_BatchOutcome as BatchOutcome, type destination_BatchRegistry as BatchRegistry, type destination_BreakerOptions as BreakerOptions, type Code$1 as Code, type Config$5 as Config, type Context$5 as Context, type Credentials$2 as Credentials, type destination_DLQ as DLQ, type destination_Data as Data, type destination_Destinations as Destinations, type Env$3 as Env, type destination_EnvObserve as EnvObserve, type Init$3 as Init, type destination_InitDestinationEntry as InitDestinationEntry, type destination_InitDestinations as InitDestinations, type destination_InitDestinationsOf as InitDestinationsOf, 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_Queued as Queued, 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>> {
@@ -1531,6 +1701,12 @@ interface PushResult {
     invalid?: boolean;
     /** Human-readable failure reason when ok is false. */
     error?: string;
+    /**
+     * Why the push failed when `ok` is false without a `failed` entry: a full
+     * pre-run queue (`queue-full`), a transformer that threw (`transformer`)
+     * or is not ready, a rule `condition` that threw (`mapping`).
+     */
+    reason?: FailureReason;
 }
 type Layer = Array<IArguments | DeepPartialEvent | unknown[]>;
 
@@ -1667,6 +1843,12 @@ interface Config$4<T extends TypesGeneric$2 = Types$3> {
     state?: State | State[];
     init?: boolean;
     disabled?: boolean;
+    /**
+     * Timeout in ms (default 10000) for `init` and for each `push`: one that
+     * does not settle within this window fails the push with code `timeout`;
+     * the next push retries the init.
+     */
+    timeout?: number;
     /** Return this value instead of calling push(). Global mock for all chains. */
     mock?: unknown;
     /** Path-specific mock values keyed by chain path (e.g., "destination.ga4.before"). Takes precedence over global mock. */
@@ -1727,8 +1909,10 @@ interface ChainCopy<E = DeepPartialEvent> {
  * 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.
+ * - dropped (a transformer returned `false`): `copies` empty, `droppedBy`
+ *   names the transformer.
+ * - failed (a transformer threw, or its `init` threw or returned `false`):
+ *   `failure` names it and carries the reason; not a drop.
  * - 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`.
@@ -1741,6 +1925,17 @@ interface ChainResult {
     stopped?: true;
     /** Transformer that dropped or stopped the chain. */
     droppedBy?: string;
+    /**
+     * A transformer that threw or could not start: the failed copy ends (not
+     * a drop), and the position answers `ok: false` with this reason. Other
+     * copies of a fork still go on in `copies`.
+     */
+    failure?: ChainFailure;
+}
+/** A transformer in a chain that failed: its id and why. */
+interface ChainFailure {
+    by: string;
+    reason: FailureReason;
 }
 /**
  * The main transformer function.
@@ -1762,10 +1957,10 @@ type Fn$2<T extends TypesGeneric$2 = Types$3, E = DeepPartialEvent> = (event: E,
  *
  * @param context - Transformer context
  * @returns void - initialization successful
- * @returns false - initialization failed, skip this transformer
+ * @throws StepError - initialization failed; the push fails
  * @returns Config<T> - return updated config
  */
-type InitFn$1<T extends TypesGeneric$2 = Types$3> = (context: Context$4<T>) => PromiseOrValue<void | false | Config$4<T>>;
+type InitFn$1<T extends TypesGeneric$2 = Types$3> = (context: Context$4<T>) => PromiseOrValue<void | Config$4<T>>;
 /**
  * Transformer instance returned by Init function.
  */
@@ -1847,6 +2042,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_ChainFailure = ChainFailure;
 type transformer_ChainResult = ChainResult;
 type transformer_InitTransformer<T extends TypesGeneric$2 = Types$3> = InitTransformer<T>;
 type transformer_InitTransformerEntry<T extends TypesGeneric$2> = InitTransformerEntry<T>;
@@ -1862,7 +2058,7 @@ 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_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_InitTransformerEntry as InitTransformerEntry, type transformer_InitTransformers as InitTransformers, type transformer_InitTransformersOf as InitTransformersOf, 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 };
+  export { type BaseEnv$2 as BaseEnv, type transformer_ChainCopy as ChainCopy, type transformer_ChainFailure as ChainFailure, 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_InitTransformerEntry as InitTransformerEntry, type transformer_InitTransformers as InitTransformers, type transformer_InitTransformersOf as InitTransformersOf, 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 };
 }
 
 /**
@@ -2213,6 +2409,12 @@ declare namespace Flow {
         type?: string;
         /** Optional "$code:..." init function. */
         init?: string;
+        /** Optional "$code:..." batch push function (destinations). */
+        pushBatch?: string;
+        /** Optional "$code:..." event handler (`on('consent')` and others). */
+        on?: string;
+        /** Optional "$code:..." destroy function. */
+        destroy?: string;
     }
     /**
      * Source reference with inline package syntax.
@@ -2236,7 +2438,7 @@ declare namespace Flow {
         /**
          * Inline code definition (object form only).
          *
-         * Object: `{push, type?, init?}` for inline code definition.
+         * Object: `{push, type?, init?, pushBatch?, on?, destroy?}` for inline code definition.
          * For named-export selection from a package, use the `import` field with `package`.
          */
         code?: Code;
@@ -2319,7 +2521,7 @@ declare namespace Flow {
         /**
          * Inline code definition (object form only).
          *
-         * Object: `{push, type?, init?}` for inline code definition.
+         * Object: `{push, type?, init?, pushBatch?, on?, destroy?}` for inline code definition.
          * For named-export selection from a package, use the `import` field with `package`.
          */
         code?: Code;
@@ -2383,7 +2585,7 @@ declare namespace Flow {
         /**
          * Inline code definition (object form only).
          *
-         * Object: `{push, type?, init?}` for inline code definition.
+         * Object: `{push, type?, init?, pushBatch?, on?, destroy?}` for inline code definition.
          * For named-export selection from a package, use the `import` field with `package`.
          */
         code?: Code;
@@ -2452,7 +2654,7 @@ declare namespace Flow {
         /**
          * Inline code definition (object form only).
          *
-         * Object: `{push, type?, init?}` for inline code definition.
+         * Object: `{push, type?, init?, pushBatch?, on?, destroy?}` for inline code definition.
          * For named-export selection from a package, use the `import` field with `package`.
          */
         code?: Code;
@@ -2572,6 +2774,43 @@ declare namespace Flow {
     type StepEffect = readonly [callable: string, ...args: unknown[]];
     /** The effects a step produces, in execution order. Empty = no observable effect (filtered, passthrough). */
     type StepOut = readonly StepEffect[];
+    /** How a kit boundary answers one request. */
+    interface StepAnswer {
+        status?: number;
+        body?: unknown;
+        /** The status text, which failure answers use to echo a canary. */
+        statusText?: string;
+        /** A network error, or no answer at all. */
+        error?: 'network' | 'timeout';
+        /** Answer one macrotask late (the floating-send check). */
+        late?: boolean;
+    }
+    /** Records one request at the kit boundary; returns its answer and marks it settled. */
+    type StepRecord = (effect: StepEffect) => {
+        answer: StepAnswer;
+        settle: () => void;
+    };
+    /**
+     * The browser page a web step runs on in the conformance kit and the
+     * examples runner. `@walkeros/web-core/dev` implements it as `page`.
+     */
+    interface StepPage {
+        open(record: StepRecord): StepPageSession;
+    }
+    /** One run on the page, from `open` to `close`. */
+    interface StepPageSession {
+        /** Page globals merged over an examples env's `push` (the document). */
+        globals: Record<string, unknown>;
+        /** Scripts added since `open`, with and without the loadVendor marker. */
+        scripts(): {
+            marked: number;
+            unmarked: number;
+        };
+        /** Fire `error` on every marked script (kit item 2, vendor-global). */
+        failScripts(): void;
+        /** Restore the stubs and remove the scripts added since `open`. */
+        close(): void;
+    }
     /**
      * Named example pair for a step.
      * `in` is the input to the step, `out` is the expected output.
@@ -2608,6 +2847,29 @@ declare namespace Flow {
          * When absent (default), `in` is pushed as a regular event.
          */
         command?: StepCommand;
+        /**
+         * The reported outcome of a failure or queue example (`public: false`):
+         * the step's status in the push result and its reason code. Absent means
+         * the step must not fail.
+         */
+        outcome?: StepOutcome;
+        /** What the boundary answers for this example (a failure fixture). */
+        respond?: StepRespond;
+    }
+    /** How a failure or queue example is reported in the push result. */
+    interface StepOutcome {
+        status: 'failed' | 'queued';
+        code: string;
+        retryable?: boolean;
+    }
+    /**
+     * The boundary's answer to the request an example makes: an HTTP status and
+     * body, or a network error or a timeout instead of a response.
+     */
+    interface StepRespond {
+        status?: number;
+        body?: unknown;
+        error?: 'network' | 'timeout';
     }
     /** Named step examples keyed by scenario name. */
     type StepExamples = Record<string, StepExample>;
@@ -2661,8 +2923,8 @@ interface LogContext {
  */
 type LogFn = (message: string | Error, context?: unknown | Error) => void;
 /**
- * Throw function signature - logs error then throws
- * Returns never as it always throws
+ * Throw function signature: throws an Error with the message, never logs
+ * (the catching collector logs the failure once). Returns never.
  */
 type ThrowFn = (message: string | Error, context?: unknown) => never;
 /**
@@ -2696,8 +2958,8 @@ interface Instance$3 {
      */
     debug: LogFn;
     /**
-     * Log an error message and throw an Error
-     * Combines logging and throwing in one call
+     * Throw an Error with the message. Does not log: the collector's catch
+     * writes the one line for the failure.
      */
     throw: ThrowFn;
     /**
@@ -2711,6 +2973,12 @@ interface Instance$3 {
      */
     scope: (name: string) => Instance$3;
 }
+/**
+ * Output format of a server terminal logger: one text line per call, or one
+ * JSON object per line (`severity`, `message`, `scope`, `context`, `time`),
+ * which Cloud Run, Loki and Datadog read as structured entries.
+ */
+type Format = 'text' | 'json';
 /**
  * Logger configuration options
  */
@@ -2720,6 +2988,13 @@ interface Config$3 {
      * @default Level.ERROR
      */
     level?: Level | keyof typeof Level;
+    /**
+     * Output format of a server flow's log lines (`@walkeros/core/node`'s
+     * terminal logger, used by `runneros`). Web flows log to the browser
+     * console and reject it.
+     * @default 'text'
+     */
+    format?: Format;
     /**
      * Custom log handler function
      * Receives originalHandler to preserve default behavior
@@ -2745,6 +3020,7 @@ type Factory = (config?: Config$3) => Instance$3;
 type logger_DefaultHandler = DefaultHandler;
 type logger_ErrorContext = ErrorContext;
 type logger_Factory = Factory;
+type logger_Format = Format;
 type logger_Handler = Handler;
 type logger_InternalConfig = InternalConfig;
 type logger_Level = Level;
@@ -2753,7 +3029,7 @@ type logger_LogContext = LogContext;
 type logger_LogFn = LogFn;
 type logger_ThrowFn = ThrowFn;
 declare namespace logger {
-  export { type Config$3 as Config, type logger_DefaultHandler as DefaultHandler, type logger_ErrorContext as ErrorContext, type logger_Factory as Factory, type logger_Handler as Handler, type Instance$3 as Instance, type logger_InternalConfig as InternalConfig, logger_Level as Level, type logger_LogContext as LogContext, type logger_LogFn as LogFn, type logger_ThrowFn as ThrowFn };
+  export { type Config$3 as Config, type logger_DefaultHandler as DefaultHandler, type logger_ErrorContext as ErrorContext, type logger_Factory as Factory, type logger_Format as Format, type logger_Handler as Handler, type Instance$3 as Instance, type logger_InternalConfig as InternalConfig, logger_Level as Level, type logger_LogContext as LogContext, type logger_LogFn as LogFn, type logger_ThrowFn as ThrowFn };
 }
 
 /** Collector state mapping for the `on` actions. */
@@ -3269,7 +3545,7 @@ interface Instance$1<T extends TypesGeneric = Types> {
     destroy?: DestroyFn<Config<T>, Env<T>>;
 }
 type Init<T extends TypesGeneric = Types> = (context: Context<Types<Partial<Settings<T>>, Env<T>, InitSettings<T>>>) => Instance$1<T> | Promise<Instance$1<T>>;
-type InitFn<T extends TypesGeneric = Types> = (context: Context<T>) => PromiseOrValue<void | false | Config<T>>;
+type InitFn<T extends TypesGeneric = Types> = (context: Context<T>) => PromiseOrValue<void | Config<T>>;
 type InitStore<T extends TypesGeneric = Types> = {
     code: Init<T>;
     config?: Partial<Config<T>>;
@@ -3698,10 +3974,13 @@ type SendDataValue = Property | Properties;
 type SendHeaders = {
     [key: string]: string;
 };
+/**
+ * What a transport helper (`sendWeb`, `sendServer`) resolves on success: the
+ * response body, parsed as JSON where it parses. A failure throws a
+ * `StepError` (code, status, retryable, body) instead.
+ */
 interface SendResponse {
-    ok: boolean;
     data?: unknown;
-    error?: string;
 }
 
 /**
@@ -3822,12 +4101,9 @@ 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' | 'dropped' | 'unknown';
+    skipReason?: FlowState['skipReason'];
     /** Error info when the branch failed. */
-    error?: {
-        name?: string;
-        message: string;
-    };
+    error?: FlowState['error'];
     /** Outbound payload of the branch, when captured. */
     out?: unknown;
     /** Vendor calls recorded on the branch's out record, when captured. */
@@ -3864,12 +4140,9 @@ interface JourneyHop {
     /** Outbound event/payload for the hop, when captured (trace level). */
     out?: unknown;
     /** Error info when the hop's terminal phase is error. */
-    error?: {
-        name?: string;
-        message: string;
-    };
+    error?: FlowState['error'];
     /** Skip discriminator when the hop's terminal phase is skip. */
-    skipReason?: 'consent' | 'cache_hit' | 'sampled_out' | 'disabled' | 'dropped' | 'unknown';
+    skipReason?: FlowState['skipReason'];
     /** Matched mapping rule, when one matched. */
     mappingKey?: string;
     /** Matched contract rule, when one matched. */
@@ -4045,11 +4318,11 @@ 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.
+     * The only source for non-deferred `$env` references: `$env.NAME` reads
+     * this map, then the inline `:default`, and never the ambient environment
+     * (`process.env`). Without it, a non-deferred `$env.NAME` takes its default
+     * or throws `FlowReferenceError`. A runtime that means its own environment
+     * passes it explicitly (`{ env: process.env }`).
      */
     env?: Readonly<Record<string, string | undefined>>;
     /**
@@ -4264,6 +4537,11 @@ declare function createDestination<I extends Instance$5>(baseDestination: I, con
  */
 declare function deepMerge<T extends Record<string, unknown>>(target: T, source: Record<string, unknown>): T;
 
+/**
+ * Names `getEvent` knows: the standard events plus the generic default
+ * `entity action`. Any other name does not compile.
+ */
+type StandardEventName = 'entity action' | 'cart view' | 'checkout view' | 'order complete' | 'page view' | 'product add' | 'product view' | 'product visible' | 'promotion visible' | 'session start';
 /**
  * Creates a complete event with default values.
  * Used for testing and debugging.
@@ -4277,14 +4555,18 @@ declare function deepMerge<T extends Record<string, unknown>>(target: T, source:
  */
 declare function createEvent(props?: DeepPartialEvent): Event;
 /**
- * Creates a complete event with default values based on the event name.
+ * Creates a complete standard event with default values based on its name.
  * Used for testing and debugging.
  *
- * @param name - The name of the event to create.
+ * The output is stable: the timestamp is fixed and the id is derived from the
+ * name (16 lowercase hex characters), so the same name gives the same event on
+ * every call, run and day. Events with other names use `createEvent`.
+ *
+ * @param name - The standard event to create.
  * @param props - Properties to override the default values.
  * @returns A complete event.
  */
-declare function getEvent(name?: string, props?: DeepPartialEvent): Event;
+declare function getEvent(name?: StandardEventName, props?: DeepPartialEvent): Event;
 
 declare function getId(length?: number, charset?: string): string;
 
@@ -4446,13 +4728,6 @@ declare function isCommand(entity: string): entity is "walker";
  * @returns True if the value is defined, false otherwise.
  */
 declare function isDefined<T>(val: T | undefined): val is T;
-/**
- * Checks if a value is an element or the document.
- *
- * @param elem The value to check.
- * @returns True if the value is an element or the document, false otherwise.
- */
-declare function isElementOrDocument(elem: unknown): elem is Element;
 /**
  * Checks if a value is a function.
  *
@@ -4832,7 +5107,10 @@ declare function tryCatchAsync<P extends unknown[], R>(fn: (...args: P) => R, on
  * violations or explicit fail-stop signals.
  */
 declare class FatalError extends Error {
-    constructor(message: string, options?: ErrorOptions);
+    cause?: unknown;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
 }
 
 /**
@@ -4846,6 +5124,21 @@ declare class InvalidEventError extends Error {
     constructor(message: string);
 }
 
+/**
+ * Default per-destination delivery timeout in ms. Applied when a destination's
+ * `config.timeout` is `0` or undefined. A hung delivery is converted into a
+ * counted DLQ failure after this window so one slow destination never wedges
+ * the collector push.
+ */
+declare const DEFAULT_DESTINATION_TIMEOUT_MS = 10000;
+/**
+ * Resolve the effective delivery timeout for a destination. A positive number
+ * wins; `0` or undefined falls back to {@link DEFAULT_DESTINATION_TIMEOUT_MS}.
+ * The collector races deliveries with it and `loadVendor` measures its vendor
+ * deadline with it, so both use one definition.
+ */
+declare function resolveDestinationTimeout(timeout?: number): number;
+
 /**
  * A utility function that wraps a function with hooks.
  *
@@ -5071,7 +5364,7 @@ type VerifyParams = VerifyAudience & {
     source: 'url' | 'storage';
     /** Epoch milliseconds. Injected so tests and the server control the clock. */
     now: number;
-    /** Defaults to globalThis.crypto. Injectable for jsdom/node tests. */
+    /** Defaults to the global crypto. Injectable for jsdom/node tests. */
     crypto?: PreviewCrypto;
 };
 /** A grant handed over in a URL is only accepted this long after `iat`. */
@@ -5101,29 +5394,6 @@ declare const MAX_SESSION_MS: number;
  * only ever decides which rejection reason comes back.
  */
 declare function verifyActivation(raw: string, params: VerifyParams): Promise<VerifyResult>;
-interface SwapActivatorConfig {
-    keyring: PreviewKey[];
-    iss: string;
-    /** This bundle's project binding. Absent on demo hosts (see acceptForeign). */
-    pb?: string;
-    acceptForeign?: boolean;
-    demoAllowlist?: string[];
-    /** Bare CDN hostname, e.g. 'cdn.walkeros.io'. */
-    previewOrigin: string;
-    /** Injectable for tests. */
-    now?: () => number;
-    crypto?: PreviewCrypto;
-}
-/**
- * Storage slot for the session-forwarding companion grant. The web arm never
- * verifies it (it is session-bound by design; the session container is its
- * verifier) — the activator only ferries it from the activation URL into
- * storage, where the seamed preview artifact reads it to stamp the
- * `X-Walkeros-Preview` header. It lives and dies with the activation state:
- * set (or cleared) whenever a URL activation succeeds, cleared whenever the
- * stored activation clears.
- */
-declare const SESSION_STORAGE_KEY = "elbPreviewSession";
 /**
  * Storage slot for the observe ingest credential companion (`obsw_...`), a
  * plaintext bearer credential riding the activation URL. The web arm never
@@ -5134,18 +5404,6 @@ declare const SESSION_STORAGE_KEY = "elbPreviewSession";
  * stored activation clears.
  */
 declare const OBSERVE_STORAGE_KEY = "elbObserve";
-/**
- * Decide whether a preview bundle should boot in place of this bundle's own flow.
- *
- * Returns true iff a preview took over, in which case the caller must not boot
- * the production flow. Every failure path deterministically returns false: the
- * loader never throws, never retries, and never leaves a page without a walker.
- *
- * Anti-griefing invariant: a rejected URL grant never touches stored state,
- * the activator falls back to the stored grant instead. Only a failing stored
- * grant clears storage (self-heal), plus `off` and `swap-failed`.
- */
-declare function browserSwapActivator(cfg: SwapActivatorConfig): Promise<boolean>;
 
 /** Where a Tag Mode script comes from and whose message may request it. */
 interface MoinTarget {
@@ -5157,14 +5415,6 @@ interface MoinTarget {
 /** The link parameter that arms the loader; its value is ignored. */
 declare const MOIN_PARAM = "elbMoin";
 declare const MOIN_PRODUCTION: MoinTarget;
-/**
- * The Tag Mode loader. Armed only by `?elbMoin` or the tab flag it leaves in
- * sessionStorage, and only in the top frame; it then waits for one message
- * from `target.app` naming a script by its hash, and loads that script from
- * `target.base` with the same hash as its integrity. Not armed, it adds no
- * listener, makes no request and writes nothing.
- */
-declare function moin(target?: MoinTarget): void;
 
 /**
  * Pure assembly of raw `FlowState` records into cross-runtime journeys, one per
@@ -5488,6 +5738,15 @@ declare function fetchPackageSchema(packageName: string, options?: {
     client?: string;
 }): Promise<WalkerOSPackageInfo>;
 
+/**
+ * The keys a named contract rule may carry, one list for the flow schema and
+ * validate; `config-drift.test-d.ts` fails the build when it and
+ * `Flow.ContractRule` drift apart. Sections such as `globals` or `consent`
+ * are not among them: nothing enforces them, so a rule on those event parts
+ * goes into `schema`. A plain literal, so a bundle that does not use it drops
+ * it.
+ */
+declare const CONTRACT_RULE_KEYS: readonly ["extend", "tagging", "description", "events", "schema"];
 /** Options for {@link resolveContracts}. */
 interface ResolveContractsOptions {
     /**
@@ -5715,14 +5974,27 @@ declare function toEventList(body: unknown): DeepPartialEvent[];
  */
 declare function isBatchBody(body: unknown): boolean;
 /**
- * The outcome of delivering one event of a batch.
+ * The answer text when a resend could still deliver the event. The step and
+ * its error stay in the collector's cause line.
+ */
+declare const EVENT_NOT_PROCESSED = "Event was not processed";
+/**
+ * The answer text of a fault that threw, the push included. Its message can
+ * carry paths, dependency names or config details, so it goes to the log only.
+ */
+declare const INTERNAL_SERVER_ERROR = "Internal server error";
+/**
+ * The outcome of delivering one event, as a producer is answered.
  *
  * `id` is present when the event was accepted and minted one. `error` is
- * present when it was not accepted.
+ * present when it was not accepted, with the HTTP `status` a single event is
+ * answered with: 400 for invalid input, 500 when a resend could still
+ * deliver it. A batch answers through `batchResponse`.
  */
 interface EventOutcome {
     id?: string;
     error?: string;
+    status?: 400 | 500;
 }
 /** A batch response: the status to answer with, and the body to send. */
 interface BatchResponse {
@@ -5751,19 +6023,33 @@ interface BatchResponse {
  */
 declare function batchResponse(outcomes: EventOutcome[]): BatchResponse;
 /**
- * Maps a collector push result onto a batch event outcome.
+ * Maps a push result onto the outcome a producer is answered with, the one
+ * place an HTTP source decides it (`acknowledge`):
+ * - `ack`: accepted, with the event id. This includes a failure a resend
+ *   cannot fix: the event is in the DLQ and its cause line is logged.
+ * - `retry`: 500 with a fixed text. The step and its error stay in the
+ *   collector's cause line; a public client cannot act on them.
+ * - `reject`: 400 with the reason, which describes the producer's own input.
  *
- * @param result The push result, or undefined when the push returned none.
+ * @param result The push result.
  * @returns The outcome for this event.
  */
-declare function pushResultToOutcome(result: {
-    ok?: boolean;
-    invalid?: boolean;
-    error?: string;
-    event?: {
-        id?: string;
-    };
-}): EventOutcome;
+declare function pushResultToOutcome(result: PushResult): EventOutcome;
+/** What a producer does with the message that carried a push. */
+type Acknowledgement = 'ack' | 'retry' | 'reject';
+/**
+ * Decides from a push result whether a producer acks, retries or rejects the
+ * message that carried it: invalid input is `reject`, a delivered or queued
+ * event `ack`. A failure is `retry` when any of its reasons is retryable and
+ * `ack` when every reason is deterministic (a redelivery cannot fix a missing
+ * setting or a 4xx; the event is in the DLQ and its cause line is logged). A
+ * failure without any reason is `retry`, so an unclassified failure never
+ * deletes a message. Only `retryable` is read, never an error text.
+ *
+ * @param result The push result.
+ * @returns `ack`, `retry` or `reject`.
+ */
+declare function acknowledge(result: PushResult): Acknowledgement;
 
 /**
  * Compiles a match expression into a closure for fast runtime evaluation.
@@ -6020,7 +6306,13 @@ interface CacheResult {
  */
 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>;
+/**
+ * Look a cache rule's key up in its store. A read that throws (a refused or
+ * failed request, not a miss) is a MISS for that event, reported once per
+ * cause under the store's step through the collector's cause log. Without a
+ * collector there is nowhere to report, and the throw propagates.
+ */
+declare function checkCache(compiled: CompiledCache, store: Instance$1, context: Record<string, unknown>, namespace?: string, collector?: Instance$6): 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>;
 
@@ -6072,16 +6364,6 @@ declare function readCacheEnvelope(stored: StoreValue | undefined, now?: () => n
     expired: true;
 } | undefined;
 
-/**
- * Thrown when a value cannot be serialized (e.g. a cyclic structure that
- * `JSON.stringify` rejects). Catchable and distinguishable from a raw
- * `TypeError` leaking out of the platform JSON implementation.
- */
-declare class StoreCodecError extends Error {
-    constructor(message: string, options?: {
-        cause?: unknown;
-    });
-}
 /**
  * Recursive type guard: the restored value is structurally a `StoreValue`.
  * The single restore walk (`fromSerializableWith`) is JSON-derived plus
@@ -6096,15 +6378,6 @@ declare class StoreCodecError extends Error {
  * `undefined`; this only mirrors what survives serialization.
  */
 declare function isStoreValue(value: unknown): value is StoreValue;
-/**
- * Serialize a `StoreValue` to its UTF-8 JSON byte payload. Throws
- * `StoreCodecError` if the value cannot be encoded (e.g. a cyclic structure).
- */
-declare function serializeStoreValue(value: StoreValue): Uint8Array;
-/**
- * Restore a `StoreValue` from its UTF-8 JSON byte payload (or a JSON string).
- */
-declare function deserializeStoreValue(raw: Uint8Array | string): StoreValue;
 
 /**
  * Resolve a store by id. An `undefined` id falls back to the default
@@ -6135,8 +6408,11 @@ declare function compileState(state: State | State[]): State[];
  * Each entry is fail-open: a store or resolution error is logged and the
  * event is left unmutated, the chain continues. An unknown store logs an
  * error and a `file: true` store is skipped with a warning. A key that does
- * not resolve warns; a store miss is silent. Only `FatalError` rethrows (via
- * `getMappingValue`).
+ * not resolve is reported at ERROR (the enrichment is lost); a store miss is
+ * silent. A read that throws is a miss for that event (a `get` applies its
+ * fallbacks) and is reported once per cause; a merge whose read throws skips
+ * its write, since a blind overwrite would drop the stored fields. Only
+ * `FatalError` rethrows (via `getMappingValue`).
  */
 declare function applyState<E extends DeepPartialEvent>(states: State[], getStore: GetStore, event: E, collector: Instance$6, ingest: Record<string, unknown> | undefined): Promise<E>;
 
@@ -6212,6 +6488,14 @@ declare function getStepRuntimeProps(step: object, kind: Flow.StepKind): Record<
 declare const STEP_OPERATIVE_FIELDS: {
     readonly [K in Flow.StepKind]: readonly StepField<K>[];
 };
+type StepFunctionKey = Exclude<keyof Flow.Code, 'type'>;
+/**
+ * The functions inline `code` defines, each a `$code:` string. One list for
+ * `Flow.Code`, the flow schema's `CodeSchema`, the bundler's emitter and
+ * validate. `config-drift.test-d.ts` fails the build when it and `Flow.Code`
+ * drift apart. A plain literal, so a bundle that does not use it drops it.
+ */
+declare const STEP_FUNCTION_KEYS: readonly ["push", "pushBatch", "init", "on", "destroy"];
 type StepEntryErrorCode = 'UNKNOWN_KEY' | 'CONFLICT' | 'MISSING_PACKAGE' | 'OBSOLETE_CODE_STRING' | 'INVALID_IMPORT' | 'INVALID_CODE_SHAPE';
 interface StepEntryValidation {
     ok: boolean;
@@ -6220,6 +6504,11 @@ interface StepEntryValidation {
     key?: string;
 }
 declare function validateStepEntry(entry: Record<string, unknown>, kind: Flow.StepKind): StepEntryValidation;
+/**
+ * Every top-level key of a step entry the runtime does not know, in entry
+ * order: the keys {@link validateStepEntry} rejects as `UNKNOWN_KEY`.
+ */
+declare function getUnknownStepKeys(entry: Record<string, unknown>, kind: Flow.StepKind): string[];
 declare function isPathStepEntry(entry: Record<string, unknown>, kind: Flow.StepKind): boolean;
 
 /**
@@ -6251,6 +6540,39 @@ declare function getTransformerMapping<M>(entry: TransformerMappingEntry<M>): M
  */
 declare function getTransformerMappingWarnings(entry: TransformerMappingEntry): string[];
 
+/** A position a mapping runs at. */
+type MappingPosition = 'source' | 'transformer' | 'destination';
+/**
+ * Mapping fields that do nothing at a position, one table for the three.
+ * - transformer: the mapping only mutates the event; config `policy` and a
+ *   rule's `condition`, `policy`, `name` and `ignore` apply.
+ * - source: only the edited event goes on; config `consent`, `policy` and a
+ *   rule's `condition`, `policy`, `name` and `ignore` apply. A rule's
+ *   `consent` is not listed here.
+ * - destination: a rule's `extend` is merged only by a package onto its own
+ *   shipped rules (`@walkeros/transformer-ga4`'s `settings.mapping`).
+ */
+declare const MAPPING_NO_OPS: Record<MappingPosition, {
+    config: ReadonlyArray<keyof Config$7>;
+    rule: ReadonlyArray<keyof Rule>;
+}>;
+/**
+ * Dotted paths of the fields in `mapping` that do nothing at `position`,
+ * rooted at `field`. Rules in array form are indexed.
+ */
+declare function getMappingNoOpPaths(position: MappingPosition, mapping: unknown, field: string): string[];
+/**
+ * Dotted paths of the `keys` set in a step config, rooted at `field`:
+ * config-level keys (any config key, `batch` included), then each mapping
+ * rule's keys. Rules in array form are indexed.
+ */
+declare function getMappingKeyPaths(mapping: unknown, field: string, keys: {
+    config: ReadonlyArray<string>;
+    rule: ReadonlyArray<keyof Rule>;
+}): string[];
+/** The message naming no-op paths at a position and what applies there. */
+declare function getMappingNoOpMessage(position: MappingPosition, paths: string[]): string;
+
 type StepOut = Flow.StepOut;
 /**
  * Format a step example's `out` as readable code for docs/app rendering.
@@ -6283,8 +6605,16 @@ declare const REF_VAR_FULL: RegExp;
 declare const REF_VAR_INLINE: RegExp;
 declare const REF_ENV: RegExp;
 declare const REF_CONTRACT: RegExp;
+/**
+ * Regex source (a string, not a RegExp) of the flow name a `$flow`
+ * reference can carry: a letter or `_`, then letters, digits, `_` or `-`
+ * (`tracking-server`). Every `$flow` pattern is built from it.
+ */
+declare const REF_FLOW_NAME = "[a-zA-Z_][a-zA-Z0-9_-]*";
 /** Whole-string `$flow.<name>(.<path>)?`: cross-flow value reference. */
 declare const REF_FLOW: RegExp;
+/** Global inline: every `$flow.<name>(.<path>)?` inside a larger string. */
+declare const REF_FLOW_INLINE: RegExp;
 declare const REF_STORE: RegExp;
 declare const REF_SECRET: RegExp;
 declare const REF_CODE_PREFIX = "$code:";
@@ -6296,4 +6626,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, type BuildFlag, CLOCK_SKEW_MS, cache as Cache, type CacheEnvelope, type CacheResult, type ChainContinuation, type ChainFrame, type ChainStep, type ClickIdEntry, collector as Collector, type CompiledCache, Const, context as Context, type Credential, type Debounced, destination as Destination, type DestroyContext, type DestroyFn, type DroppedCounters, ENV_MARKER_PREFIX, elb as Elb, type EmitFn, type EventOutcome, type ExampleSummary, FatalError, Flow, type FlowConfigResolver, FlowCycleError, FlowReferenceError, type FlowState, type FlowStateBatch, type FlowStatePhase, type FlowStepType, type GetStore, hint as Hint, hooks as Hooks, type Ingest, type IngestEnvelope, type IngestMeta, InvalidEventError, type Journey, type JourneyAssembly, type JourneyBranch, type JourneyCorrelation, type JourneyEntry, type JourneyGap, type JourneyHop, type JourneyHopStatus, type JourneyPlatform, type JourneyStatus, type JourneyTopology, type JourneyTopologyNode, type JourneyUnattributed, type JsonSchema, Level, lifecycle as Lifecycle, type LifecycleContext, logger as Logger, MAX_SESSION_MS, MOIN_PARAM, MOIN_PRODUCTION, mapping as Mapping, type MarketingParameters, matcher as Matcher, type MockLogger, type MoinTarget, type NextSteps, type NodeLikeRequest, OBSERVE_ENV_KEY, OBSERVE_STORAGE_KEY, type Observe, type ObserveCredential, type ObserveServer, type ObserveWeb, type ObservedEnv, type ObserverFn, on as On, type ParsedGrant, type ParsedTraceparent, type PosterFetch, type PosterResponse, type PreviewCrypto, type PreviewFailure, type PreviewKey, type PreviewSubtle, REF_CODE_PREFIX, REF_CONTRACT, REF_ENV, REF_FLOW, REF_SECRET, REF_STORE, REF_VAR_FULL, REF_VAR_INLINE, RESERVED_WINDOW_GLOBALS, request as Request, type ResolveContractsOptions, type ResolveOptions, type RespondFn, type RespondOptions, type RouteContinuation, type RouteDecision, type RouteGraphNode, type RouteLabel, SECRET_MARKER_PREFIX, SESSION_STORAGE_KEY, STEP_FIELD_ROLES, STEP_OPERATIVE_FIELDS, type ScheduleOptions, type SendDataValue, type SendHeaders, type SendResponse, type ServiceAccount, type SetupFn, simulation as Simulation, source as Source, type State, type StepEntryErrorCode, type StepEntryValidation, type StepField, type StepFieldRole, type StepKind, type StorageType, store as Store, StoreCodecError, type SwapActivatorConfig, type TelemetryLevel, type TelemetryOptions, type TelemetryOptionsSupplier, type Timer, transformer as Transformer, type TransformerMappingEntry, trigger as Trigger, URL_WINDOW_MS, type ValidateEvents, type VerifyParams, type VerifyResult, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, type WindowCollectorCheck, advanceChain, anonymizeIP, applyState, applyUpdate, assembleJourneys, assign, batchResponse, branch, browserSwapActivator, buildScopeFromNodeRequest, castToProperty, castValue, checkCache, checkWindowCollector, clone, compileCache, compileMatcher, compileState, createBatchedPoster, createDestination, createEvent, createIngest, createLogger, createMappingRoot, createMockContext, createMockLogger, createRespond, createTelemetryObserver, createTimer, debounce, deepMerge, defaultClickIds, deleteByPath, deriveSpanId, deserializeStoreValue, emitStep, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, formatOut, getBrowser, getBrowserVersion, getByPath, getDeviceType, getErrorMessage, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingValue, getMarketingParameters, getNextSteps, getOS, getOSVersion, getPlatform, getRouteGraph, getSpanId, getStepFieldRole, getStepRuntimeProps, getTraceId, getTraceUntil, getTransformerMapping, getTransformerMappingWarnings, isArguments, isArray, isBatchBody, isBoolean, isChainContinuation, isCommand, isDefined, isElementOrDocument, isEnvObserve, isFunction, isNumber, isObject, isPathStepEntry, isPropertyType, isRouteArray, isRouteConfigEntry, isRouteContinuation, isSameType, isSampled, isScope, isStoreValue, isString, isThenable, mcpError, mcpResult, mergeContractSchemas, mergeMappingRule, mockEnv, moin, normalizeBody, normalizeHeaders, normalizeQuery, observeEnv, observeFromEnv, packageNameToVariable, parseCallPath, parseGrant, parseObserveCredential, parseTraceparent, parseUserAgent, processEventMapping, pushResultToOutcome, readCacheEnvelope, requestToData, requestToParameter, resolveContracts, resolveSetup, resolveTelemetryOptions, scanFlowRefs, serializeStoreValue, setByPath, setTraceUntil, startChain, stepId, storeCache, throttle, throwError, toEventList, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateStepEntry, verifyActivation, walkPath, wrapCacheEnvelope, wrapCondition, wrapFn, wrapValidate };
+export { type Acknowledgement, type ActivationGrant, type AssembleJourneysOptions, type BatchResponse, type BatchedPosterOptions, type BreakerState, type BuildFlag, CLOCK_SKEW_MS, CONTRACT_RULE_KEYS, cache as Cache, type CacheEnvelope, type CacheResult, type CauseKey, type CauseLog, type CauseLogOptions, type CauseLogger, type ChainContinuation, type ChainFrame, type ChainStep, type ClickIdEntry, collector as Collector, type CompiledCache, Const, context as Context, type Credential, DEFAULT_DESTINATION_TIMEOUT_MS, type Debounced, destination as Destination, type DestroyContext, type DestroyFn, type DroppedCounters, ENV_MARKER_PREFIX, EVENT_NOT_PROCESSED, elb as Elb, type EmitFn, type EventOutcome, type ExampleSummary, type FailureReason, FatalError, Flow, type FlowConfigResolver, FlowCycleError, FlowReferenceError, type FlowState, type FlowStateBatch, type FlowStatePhase, type FlowStepType, type GetStore, hint as Hint, hooks as Hooks, INTERNAL_SERVER_ERROR, 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, MAPPING_NO_OPS, MAX_SESSION_MS, MOIN_PARAM, MOIN_PRODUCTION, mapping as Mapping, type MappingPosition, type MarketingParameters, matcher as Matcher, type MockLogger, type MoinTarget, type NextSteps, type NodeLikeRequest, OBSERVE_ENV_KEY, OBSERVE_STORAGE_KEY, type Observe, type ObserveCredential, type ObserveServer, type ObserveSlot, type ObserveWeb, type ObservedEnv, type ObserverFn, on as On, type ParsedGrant, type ParsedTraceparent, type PosterFetch, type PosterResponse, type PreviewCrypto, type PreviewFailure, type PreviewKey, type PreviewSubtle, type QueueReason, type QueuedReason, REF_CODE_PREFIX, REF_CONTRACT, REF_ENV, REF_FLOW, REF_FLOW_INLINE, REF_FLOW_NAME, REF_SECRET, REF_STORE, REF_VAR_FULL, REF_VAR_INLINE, RESERVED_WINDOW_GLOBALS, request as Request, type ResolveContractsOptions, type ResolveOptions, type RespondFn, type RespondOptions, type RouteContinuation, type RouteDecision, type RouteGraphNode, type RouteLabel, SECRET_MARKER_PREFIX, STEP_FIELD_ROLES, STEP_FUNCTION_KEYS, STEP_OPERATIVE_FIELDS, type ScheduleOptions, type SendDataValue, type SendHeaders, type SendResponse, type ServiceAccount, type SetupFn, simulation as Simulation, source as Source, type StandardEventName, type State, type StepEntryErrorCode, type StepEntryValidation, StepError, type StepErrorOptions, type StepField, type StepFieldRole, type StepFunctionKey, type StepKind, type StorageType, store as Store, type TelemetryLevel, type TelemetryOptions, type TelemetryOptionsSupplier, type Timer, transformer as Transformer, type TransformerMappingEntry, trigger as Trigger, URL_WINDOW_MS, type ValidateEvents, type VerifyParams, type VerifyResult, walkeros as WalkerOS, type WalkerOSPackage, type WalkerOSPackageInfo, type WalkerOSPackageMeta, type WindowCollectorCheck, acknowledge, advanceChain, anonymizeIP, applyState, applyUpdate, assembleJourneys, assign, batchResponse, branch, buildScopeFromNodeRequest, castToProperty, castValue, checkCache, checkWindowCollector, clone, compileCache, compileMatcher, compileState, createBatchedPoster, createCauseLog, createDestination, createEvent, createIngest, createLogger, createMappingRoot, createMockContext, createMockLogger, createRespond, createTelemetryObserver, createTimer, debounce, deepMerge, defaultClickIds, deleteByPath, deriveSpanId, emitStep, fetchPackage, fetchPackageSchema, filterValues, flattenIncludeSections, formatOut, getBrowser, getBrowserVersion, getByPath, getDeviceType, getErrorMessage, getEvent, getFlowSettings, getGrantedConsent, getHeaders, getId, getMappingEvent, getMappingKeyPaths, getMappingNoOpMessage, getMappingNoOpPaths, getMappingValue, getMarketingParameters, getNextSteps, getOS, getOSVersion, getPlatform, getRouteGraph, getSpanId, getStepFieldRole, getStepRuntimeProps, getTraceId, getTraceUntil, getTransformerMapping, getTransformerMappingWarnings, getUnknownStepKeys, isArguments, isArray, isBatchBody, isBoolean, isChainContinuation, isCommand, isDefined, isEnvObserve, isFunction, isNumber, isObject, isPathStepEntry, isPropertyType, isRouteArray, isRouteConfigEntry, isRouteContinuation, isSameType, isSampled, isScope, isStoreValue, isString, isThenable, mcpError, mcpResult, mergeContractSchemas, mergeMappingRule, mockEnv, networkErrorMessage, normalizeBody, normalizeHeaders, normalizeQuery, observeEnv, observeFromEnv, packageNameToVariable, parseCallPath, parseGrant, parseObserveCredential, parseTraceparent, parseUserAgent, processEventMapping, pushResultToOutcome, readCacheEnvelope, reportCause, requestToData, requestToParameter, resolveContracts, resolveDestinationTimeout, resolveSetup, resolveTelemetryOptions, scanFlowRefs, setByPath, setTraceUntil, startChain, stepCall, stepId, storeCache, throttle, throwError, toEventList, toFailureReason, transformData, traverseEnv, trim, tryCatch, tryCatchAsync, useHooks, validateStepEntry, verifyActivation, walkPath, wrapCacheEnvelope, wrapCondition, wrapFn, wrapValidate };