@walkeros/core 4.4.0-next-1785285516008 → 4.5.0

package/CHANGELOG.md

@@ -1,6 +1,39 @@
 # @walkeros/core
 
-## 4.4.0-next-1785285516008
+## 4.5.0
+
+### Minor Changes
+
+- 63845bb: The Express source's `async` option now resolves per HTTP method: a
+  boolean still applies to the whole source, and a record like `{ "GET": true }`
+  or `{ "POST": false }` overrides one method while the other keeps its default.
+  The default changed: GET is now synchronous, so a step such as the file
+  transformer or a cache can serve real content instead of the tracking GIF,
+  while POST keeps the fast respond-first acknowledgement. To restore
+  respond-first GET set `async: true` or `async: { "GET": true }`; configs that
+  set `async: false` only to fix asset serving can drop it.
+
+### Patch Changes
+
+- 79cdcb0: Server sources answer rejected client input with 4xx JSON instead of
+  unhandled errors or 500s: unparseable bodies return 400 at the HTTP boundary,
+  and invalid events return 400 with the reason wherever the response is still
+  open (synchronous handling; in the express default respond-first mode the 200
+  ack has already been sent, so the rejection surfaces as a warn and a counter
+  instead) (`push` resolves `{ok: false, invalid: true, error}`). Genuine
+  pipeline failures return 500 instead of `success: true`. Invalid input now
+  counts on `collector.status.sources.<id>.rejected` instead of inflating
+  `status.failed`. The express source no longer sends `X-Powered-By` and now
+  sets `X-Content-Type-Options: nosniff` on every response.
+- 756b571: Server sources now share one request scope and one event envelope, so
+  `config.ingest` paths and POST body forms behave identically on Express,
+  Fetch, Lambda and Cloud Functions. Batches and bare arrays are accepted
+  everywhere, and a destination before-chain fan-out no longer drops all but the
+  first event. Breaking: AWS `requestContext.*` moves under `raw.*`, Express
+  drops `protocol` and `hostname`, and Fetch `{ fn }` header mappings become
+  `{ key: 'headers.*' }`. See the migration guide.
+
+## 4.4.0
 
 ### Minor Changes
 
@@ -11,6 +44,19 @@
   `parentEventId`, instead of folding them into a single row. A new optional
   `unattributed` summary reports records the assembly could not attribute to any
   event instead of dropping them silently.
+- 034b1de: Events pushed before the collector runs are now held and replayed at
+  run instead of being dropped, bounded by `queueMax`. `walker init <element>`
+  re-fires load triggers for already-tracked elements, restoring the SPA re-init
+  pattern. Queue sources start consuming at run and no longer acknowledge
+  messages the pipeline did not accept.
+- d00e2bd: A source's `env` is now unambiguously the author's dependency bag:
+  the collector-provided `push`, `elb`, `command`, `logger` and `sources` always
+  win, so setting them in `env` has no effect. Sources that need the pipeline to
+  end elsewhere declare the new `terminus`, which receives the raw event and
+  skips the pipeline entirely; previously an `env.push` silently replaced the
+  pipeline's end and disabled some, but not all, of its stages, and flows that
+  set it should move to `terminus`. Stored flows now also reject unknown keys on
+  a source entry at validation instead of silently ignoring them.
 
 ### Patch Changes
 

package/dist/dev.d.mts

@@ -3867,12 +3867,15 @@ declare namespace collector {
  * - sources: Other registered sources
  * - elb: Public API function (alias for collector.push)
  *
- * Platform-specific sources extend this with their requirements
- * (e.g., window, document, fetch, req, res)
+ * The capability keys above (plus logger) are runtime-owned: the collector
+ * applies them last, so author values for them are ignored. Platform-specific
+ * sources extend the env with their own requirements (e.g., window, document,
+ * fetch, req, res), and those author dependencies pass through untouched.
  *
  * This makes sources:
  * - Platform-agnostic (no direct dependencies)
- * - Testable (mock env for tests)
+ * - Testable (mock author dependencies via env; mock the collector boundary
+ *   via a hand-built Context or InitSource.terminus)
  * - Composable (share env between sources)
  */
 declare const BaseEnvSchema: z.ZodObject<{
@@ -3987,7 +3990,7 @@ declare const ConfigSchema$3: z.ZodObject<{
         }>]>>;
         handler: z.ZodOptional<z.ZodAny>;
     }, z.core.$strip>>;
-    async: z.ZodOptional<z.ZodBoolean>;
+    async: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodBoolean>]>>;
     setup: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
     ingest: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodArray<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>]>>;
     disabled: z.ZodOptional<z.ZodBoolean>;
@@ -4107,7 +4110,7 @@ declare const PartialConfigSchema$2: z.ZodObject<{
         }>]>>;
         handler: z.ZodOptional<z.ZodAny>;
     }, z.core.$strip>>>;
-    async: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+    async: z.ZodOptional<z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodBoolean>]>>>;
     setup: z.ZodOptional<z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>>;
     ingest: z.ZodOptional<z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodArray<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>]>>>;
     disabled: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
@@ -4243,7 +4246,7 @@ declare const InstanceSchema: z.ZodObject<{
             }>]>>;
             handler: z.ZodOptional<z.ZodAny>;
         }, z.core.$strip>>;
-        async: z.ZodOptional<z.ZodBoolean>;
+        async: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodBoolean>]>>;
         setup: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
         ingest: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodArray<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>]>>;
         disabled: z.ZodOptional<z.ZodBoolean>;
@@ -4388,7 +4391,7 @@ declare const InitSourceSchema: z.ZodObject<{
             }>]>>;
             handler: z.ZodOptional<z.ZodAny>;
         }, z.core.$strip>>>;
-        async: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+        async: z.ZodOptional<z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodBoolean>]>>>;
         setup: z.ZodOptional<z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>>;
         ingest: z.ZodOptional<z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodArray<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>]>>>;
         disabled: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
@@ -4531,7 +4534,7 @@ declare const InitSourcesSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
             }>]>>;
             handler: z.ZodOptional<z.ZodAny>;
         }, z.core.$strip>>>;
-        async: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+        async: z.ZodOptional<z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodBoolean>]>>>;
         setup: z.ZodOptional<z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>>;
         ingest: z.ZodOptional<z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodArray<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>]>>>;
         disabled: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
@@ -5112,7 +5115,7 @@ declare const SourceSchema: z.ZodObject<{
             update: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
-}, z.core.$strip>;
+}, z.core.$strict>;
 /**
  * Transformer reference schema (Flow.Transformer).
  */
@@ -5419,7 +5422,7 @@ declare const FlowSchema: z.ZodObject<{
                 update: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
-    }, z.core.$strip>>>;
+    }, z.core.$strict>>>;
     destinations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         package: z.ZodOptional<z.ZodString>;
         code: z.ZodOptional<z.ZodObject<{
@@ -5643,7 +5646,7 @@ declare const JsonSchema$1: z.ZodObject<{
                     update: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
                 }, z.core.$strip>>;
             }, z.core.$strip>>;
-        }, z.core.$strip>>>;
+        }, z.core.$strict>>>;
         destinations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             package: z.ZodOptional<z.ZodString>;
             code: z.ZodOptional<z.ZodObject<{
@@ -6278,7 +6281,7 @@ declare const configJsonSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<
                     update: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
                 }, z.core.$strip>>;
             }, z.core.$strip>>;
-        }, z.core.$strip>>>;
+        }, z.core.$strict>>>;
         destinations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             package: z.ZodOptional<z.ZodString>;
             code: z.ZodOptional<z.ZodObject<{
@@ -7678,6 +7681,14 @@ interface SourceStatus {
     count: number;
     lastAt?: number;
     duration: number;
+    /**
+     * Monotonic count of inbound input rejected before entering the pipeline:
+     * the source bumps it for HTTP-boundary rejections (unparseable body,
+     * oversized payload, unsupported charset), the collector bumps it for
+     * events rejected as invalid at the pipeline gate. Absent means no
+     * rejections were tracked.
+     */
+    rejected?: number;
 }
 interface DestinationStatus {
     count: number;
@@ -7796,6 +7807,15 @@ interface Instance$5 {
     logger: Instance$3;
     on: OnConfig;
     queue: Events;
+    /**
+     * Events pushed while `allowed === false`, held raw (pre-pipeline) and
+     * replayed FIFO by the run command. Bounded by `config.queueMax`
+     * (drop-oldest). RECORD-immediate/DELIVER-gated, extended to events.
+     */
+    preRunQueue: Array<{
+        event: DeepPartialEvent;
+        options: PushOptions;
+    }>;
     round: number;
     /** Run-scoped W3C trace id, minted on each run and stamped onto events. */
     trace?: string;
@@ -8288,6 +8308,10 @@ interface PushResult {
     failed?: Record<string, Ref>;
     /** Event was intentionally not forwarded: a transformer chain stopped it. */
     dropped?: boolean;
+    /** Event was rejected as invalid input: a client/producer fault, not a pipeline failure. */
+    invalid?: boolean;
+    /** Human-readable failure reason when ok is false. */
+    error?: string;
 }
 
 type AnyFunction<P extends unknown[] = never[], R = unknown> = (...args: P) => R;
@@ -8665,8 +8689,12 @@ interface InitTransformers {
 /**
  * Base Env interface for dependency injection into sources.
  *
- * Sources receive all their dependencies through this environment object,
- * making them platform-agnostic and easily testable.
+ * `env` is the author's dependency bag: platform and vendor dependencies are
+ * injected here, making sources platform-agnostic. The five capabilities the
+ * collector provides (`push`, `command`, `sources`, `elb`, `logger`) are
+ * runtime-owned and applied last, so author values for them are ignored. To
+ * mock the collector boundary in a test, call the factory directly with a
+ * hand-built `Context`, or declare `InitSource.terminus`.
  */
 interface BaseEnv$1 {
     [key: string]: unknown;
@@ -8733,17 +8761,18 @@ interface Config$1<T extends TypesGeneric$1 = Types$1> extends Config$7<Mapping<
     /**
      * Respond-first acknowledgement for response-producing server sources.
      *
-     * When a source produces an HTTP response (express today; future fetch /
-     * lambda), `async: true` (the default for such sources) responds 2xx
-     * ("accepted") before the event is delivered to the collector, so the
-     * client is not blocked on backend delivery. `async: false` waits for
-     * delivery to settle before responding. A 2xx means "accepted", not
-     * "delivered".
+     * `true` responds 2xx ("accepted") before the event is delivered to the
+     * collector, so the client is not blocked on backend delivery; `false`
+     * waits for delivery to settle before responding and lets the response
+     * reflect the outcome. A record configures this per source-defined key:
+     * the express source keys it by HTTP method (`GET`/`POST`) and defaults
+     * to `{ GET: false, POST: true }`, so a step can serve real content on
+     * GET while POST acks fast. A 2xx means "accepted", not "delivered".
      *
      * Browser and dataLayer sources have no HTTP response to defer and ignore
-     * this flag. The default is per source type.
+     * this flag. Defaults are per source type.
      */
-    async?: boolean;
+    async?: boolean | Record<string, boolean>;
     /** Mark as primary source; its push function becomes the exported `elb` from startFlow. */
     primary?: boolean;
     /** Defer source initialization until these collector events fire (e.g., `['consent']`). */
@@ -8755,14 +8784,15 @@ interface Config$1<T extends TypesGeneric$1 = Types$1> extends Config$7<Mapping<
     setup?: boolean | SetupOptions$1<T>;
     /**
      * Ingest metadata extraction mapping.
-     * Extracts values from raw request objects (Express req, Lambda event, etc.)
-     * using walkerOS mapping syntax. Extracted data flows to transformers/destinations.
+     * Extracts values from the normalized `Scope` the source built, using
+     * walkerOS mapping syntax. Extracted data flows to transformers and
+     * destinations. Paths resolve against the scope's fields, with no prefix.
      *
      * @example
      * ingest: {
-     *   ip: 'req.ip',
-     *   ua: 'req.headers.user-agent',
-     *   origin: 'req.headers.origin'
+     *   ip: 'ip',
+     *   ua: 'headers.user-agent',
+     *   origin: 'headers.origin'
      * }
      */
     ingest?: Data$1;
@@ -8821,6 +8851,36 @@ type ScopeEnv<T extends TypesGeneric$1 = Types$1> = Env$1<T> & {
     /** Respond function bound to this scope (undefined for scopes without a response). */
     respond?: RespondFn;
 };
+/**
+ * The normalized shape every source builds from its platform's request before
+ * calling withScope. Downstream config.ingest mappings, transformers and
+ * destinations read this shape and nothing else, so a mapping written once
+ * resolves the same on every source.
+ *
+ * A value a platform does not supply is never guessed. `ip` is the one optional
+ * field and is simply absent there; the required fields carry a documented
+ * empty value instead (`url` is `''` when the platform cannot form one). `raw`
+ * carries the untouched platform object for the cases normalization
+ * deliberately does not cover.
+ */
+interface Scope {
+    /** Uppercase HTTP method. */
+    method: string;
+    /** Absolute request URL when the platform knows it, else ''. */
+    url: string;
+    /** Pathname only, no query string, leading slash. */
+    path: string;
+    /** Query parameters. Repeated keys joined with ','. */
+    query: Record<string, string>;
+    /** Header bag. Keys lowercased. Repeated values joined with ', '. */
+    headers: Record<string, string>;
+    /** Parsed body when it parses as JSON, the raw string when it does not, undefined when there is none. */
+    body: unknown;
+    /** Client IP as the platform reports it. Absent when the platform does not report one. */
+    ip?: string;
+    /** The untouched platform object. Escape hatch, never read by walkerOS itself. */
+    raw: unknown;
+}
 /**
  * Context provided to source init function.
  * Extends base context with source-specific properties.
@@ -8830,29 +8890,32 @@ interface Context$1<T extends TypesGeneric$1 = Types$1> extends Base<Partial<Con
     /**
      * 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.
+     * normalized scope 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:
+     * Server sources normalize their platform's request into a `Scope` first,
+     * then call this once per inbound request:
      *
      * ```ts
-     * await context.withScope(req, createRespond(sender), async (env) => {
-     *   await env.push(parsedData);
+     * const scope = buildScope(req);
+     *
+     * await context.withScope(scope, createRespond(sender), async (env) => {
+     *   for (const event of toEventList(scope.body)) await env.push(event);
      * });
      * ```
      *
      * Browser sources with a single tab-lifetime scope may skip `withScope`
      * and use `env.push` directly.
      *
-     * @param rawScope - Raw input for `config.ingest` mapping (Express req,
-     *   Lambda event, fetch Request, etc.). Pass `undefined` if no ingest
-     *   mapping applies.
+     * @param rawScope - The normalized scope the source built from its
+     *   platform's request. 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.
      */
-    withScope: <R>(rawScope: unknown, respond: RespondFn | undefined, body: (env: ScopeEnv<T>) => Promise<R>) => Promise<R>;
+    withScope: <R>(rawScope: Scope | undefined, 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$1<T> | Promise<Instance$1<T>>;
 type InitSource<T extends TypesGeneric$1 = Types$1> = {
@@ -8862,6 +8925,21 @@ type InitSource<T extends TypesGeneric$1 = Types$1> = {
     primary?: boolean;
     next?: Route;
     before?: Route;
+    /**
+     * Replace the collector at the END of this source's pipeline.
+     *
+     * A terminus receives the event exactly as the source emitted it and the
+     * entire pipeline is skipped: no `before`/`next` chains, no source `cache`,
+     * no `state`, no `mapping`, no minted span id, no per-source ingest, no
+     * `respond`, no `status.sources` counting and no observability records.
+     *
+     * This is a TOTAL bypass, deliberately, so there is one thing to know rather
+     * than a list of exceptions. It exists for deterministic capture at the
+     * source→collector boundary (step examples, dev tooling). Production flows
+     * leave it unset. Runtime-only: stored-flow validation rejects unknown
+     * source keys, so a persisted flow cannot carry it.
+     */
+    terminus?: PushFn$1;
     cache?: Cache;
     state?: State | State[];
 };