@loadstrike/loadstrike-sdk 1.0.30001 → 1.0.30401

package/README.md

@@ -48,12 +48,36 @@ const scenario = LoadStrikeScenario
 
 const result = await LoadStrikeRunner
   .registerScenarios(scenario)
+  .useLoadEngineV2()
+  .withMaxInFlight(5000)
   .withRunnerKey("rkl_your_runner_key")
   .run();
 ```
 
 `run()` returns the detailed run result, including generated report files, scenario statistics, metrics, and sink status.
 
+## Load Engine V2
+
+Call `.useLoadEngineV2()` explicitly for the versioned smooth-pacing and bounded-work contract. V2 spreads fixed-rate arrivals across their interval and uses one process-wide in-flight ceiling shared by scenarios and colocated logical agents. The default is 10,000; call `.withMaxInFlight(...)` after the V2 opt-in to override it with a value from 1 through 1,000,000.
+
+The requested rate is offered scenario invocations per interval. Compare it with achieved starts, delivery percentage, scheduler lag, and transport throughput. If the generator is late or at capacity, the arrival is dropped and disclosed as a generator warning rather than counted as an application failure. One scenario invocation may contain several requests, Kafka records, or browser operations, so size Playwright workloads by browser capacity and report Kafka records and bytes per second separately.
+
+V2 supports `LoadStrikeTrafficMix` with one deterministic global rank space across its weighted lanes and agent shards. Cross-platform tracking is not yet supported by the TypeScript V2 profile and is rejected before traffic instead of running with partial accounting.
+
+Non-correlated V2 scenarios can run through the local-development cluster or a remote NATS cluster. Remote execution waits for the exact expected compatible agent set before starting; a missing result owner is reported as incomplete rather than silently producing a partial aggregate. Existing V1 cluster behavior is unchanged.
+
+HTML reports include a Generator Delivery tab whenever scheduler delivery data, raw observation delivery statistics, generator or reporting warnings, or incomplete reporting are available. Results without reporting-completeness status show N/A rather than reporting loss. Application failures remain separate from generator and reporting warnings.
+
+## Raw Iteration Reporting
+
+Observation-capable reporting sinks receive one compact record for every scenario attempt, including retry attempts and nested steps. Retries share a logical iteration ID while retaining distinct attempt indexes and final-attempt markers. Warm-up and bombing traffic, simulation and shard identity, UTC nanosecond timestamps, observed and reported latency, outcome, status code, and response size are included; reply messages, payloads, bodies, and headers are not.
+
+Portal reporting sends compressed batches, while the JSONL and generic webhook sinks preserve the canonical observation records. Custom sinks can opt in with `saveIterationBatch` or `SaveIterationBatch` while keeping all existing aggregate lifecycle callbacks unchanged. Batches flush every five seconds; the defaults and the portal-compatible common shape are 50,000 observations or 8 MiB before compression. Runs without a portal sink may select the documented larger limits. Capture and sink queues are memory bounded; buffer pressure, a single record that cannot fit a batch, and sink pressure drop only the affected reporting observations with explicit warnings instead of changing application failures. Metric-only destinations disclose their reduced observation shape. The final observation flush and optional stream-completion callback finish before `saveRunResult` or `SaveRunResult`.
+
+Portal trend p50, p75, p95, and p99 values are calculated cumulatively from every final bombing-phase outcome received for that scenario and run. Separate successful and failed distributions remain available for diagnosis; SDK-calculated percentile fields are not sent as the authoritative portal or observation-capable sink result.
+
+Use runner configuration fields such as `iterationObservationFlushIntervalSeconds`, `maxIterationObservationBufferBytes`, `maxIterationObservationsPerBatch`, `maxIterationObservationBatchBytes`, `iterationObservationSinkQueueDepth`, `iterationObservationSinkParallelism`, and `iterationObservationDrainTimeoutSeconds` when the defaults need to be adjusted within their documented bounds.
+
 ## Traffic Mixes
 
 Use `LoadStrikeTrafficMix` on Pro and Enterprise plans when one total load profile should be distributed across multiple scenario lanes. For example, a 1000 requests-per-second profile with scenario weights of 60, 30, and 10 sends roughly 600 requests per second to the first scenario, 300 to the second, and 100 to the third.