@walkeros/core 4.4.0 → 4.5.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @walkeros/core
 
+## 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

package/dist/dev.d.mts

@@ -3990,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>;
@@ -4110,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>>;
@@ -4246,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>;
@@ -4391,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>>;
@@ -4534,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>>;
@@ -7681,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;
@@ -8300,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;
@@ -8749,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']`). */
@@ -8771,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;
@@ -8837,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.
@@ -8846,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> = {

package/dist/dev.d.ts

@@ -3990,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>;
@@ -4110,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>>;
@@ -4246,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>;
@@ -4391,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>>;
@@ -4534,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>>;
@@ -7681,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;
@@ -8300,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;
@@ -8749,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']`). */
@@ -8771,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;
@@ -8837,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.
@@ -8846,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> = {