@opensip-cli/simulation 0.1.0

package/dist/framework/execution/http-target.js

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview `httpTarget` — an HTTP `Target` factory.
+ *
+ * The smallest BYO seam is a function, but most users point at an HTTP
+ * endpoint. `httpTarget` wraps the built-in `fetch` (Node 24+) into a `Target`:
+ * it forwards `ctx.signal` (so scenario abort + `abort` faults cancel the
+ * request) and **throws on a non-OK status** so the driver classifies it as a
+ * failure.
+ *
+ * Point this only at a target you own. For server-side fault injection (kill a
+ * dependency, force 500s), put a fault-injectable proxy (e.g. Toxiproxy) in
+ * front and aim `httpTarget` at the proxy — the harness drives and measures
+ * around it.
+ */
+const defaultOk = (status) => status >= 200 && status < 300;
+/** Build an HTTP {@link Target} from a URL + method/headers/body. */
+export function httpTarget(opts) {
+    const isOk = opts.okStatus ?? defaultOk;
+    /** @throws {Error} When the response status is not OK (per `isOk`). */
+    async function request(ctx) {
+        // @fitness-ignore-next-line no-raw-fetch -- BYO HTTP target for the chaos/load harness; raw fetch is the measured surface, abort handled via ctx.signal
+        const res = await fetch(opts.url, {
+            method: opts.method ?? 'GET',
+            headers: opts.headers,
+            body: opts.body,
+            signal: ctx.signal,
+        });
+        // Drain the body so the socket is freed even though we ignore the payload.
+        try {
+            await res.arrayBuffer();
+        }
+        catch {
+            // @swallow-ok best-effort body drain; already-consumed or aborted bodies are fine to ignore.
+        }
+        if (!isOk(res.status)) {
+            throw new Error(`httpTarget: ${opts.url} returned ${res.status}`);
+        }
+    }
+    return request;
+}
+//# sourceMappingURL=http-target.js.map

package/dist/framework/execution/http-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-target.js","sourceRoot":"","sources":["../../../src/framework/execution/http-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAqBH,MAAM,SAAS,GAAG,CAAC,MAAc,EAAW,EAAE,CAAC,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG,CAAC;AAE7E,qEAAqE;AACrE,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,IAAI,SAAS,CAAC;IACxC,uEAAuE;IACvE,KAAK,UAAU,OAAO,CAAC,GAAkB;QACvC,wJAAwJ;QACxJ,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE;YAChC,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,KAAK;YAC5B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,GAAG,CAAC,MAAM;SACnB,CAAC,CAAC;QACH,2EAA2E;QAC3E,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,6FAA6F;QAC/F,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,eAAe,IAAI,CAAC,GAAG,aAAa,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/framework/execution/latency-tracker.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Latency tracker for real percentile computation
+ *
+ * All samples are stored for accurate percentile computation.
+ * Sorted cache is invalidated when new samples are added.
+ * Percentiles use linear interpolation between nearest values.
+ *
+ * Suitable for simulation-scale workloads (hundreds to low thousands of samples).
+ * For workloads exceeding ~100k samples, consider a streaming percentile
+ * algorithm (e.g., t-digest or HDR histogram).
+ */
+export declare class LatencyTracker {
+    private samples;
+    private sorted;
+    private sum;
+    /**
+     * Record a latency sample.
+     * @param latencyMs - Latency value in milliseconds
+     */
+    record(latencyMs: number): void;
+    /** Get the number of recorded samples. */
+    get count(): number;
+    /** Get the average latency. */
+    get average(): number;
+    /**
+     * Compute a percentile value using linear interpolation.
+     * @param p - Percentile (0-100), e.g., 50, 95, 99
+     * @returns The latency value at the given percentile, or 0 if no samples
+     */
+    getPercentile(p: number): number;
+    /**
+     * Get a latency snapshot compatible with SimulationMetrics fields.
+     */
+    getLatencySnapshot(): {
+        avgLatencyMs: number;
+        p50LatencyMs: number;
+        p95LatencyMs: number;
+        p99LatencyMs: number;
+    };
+    /** Reset all tracked samples. */
+    reset(): void;
+    private getSorted;
+}
+//# sourceMappingURL=latency-tracker.d.ts.map

package/dist/framework/execution/latency-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"latency-tracker.d.ts","sourceRoot":"","sources":["../../../src/framework/execution/latency-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,GAAG,CAAK;IAEhB;;;OAGG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAM/B,0CAA0C;IAC1C,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,+BAA+B;IAC/B,IAAI,OAAO,IAAI,MAAM,CAGpB;IAED;;;;OAIG;IACH,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM;IAehC;;OAEG;IACH,kBAAkB,IAAI;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;KACtB;IASD,iCAAiC;IACjC,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,SAAS;CAIlB"}

package/dist/framework/execution/latency-tracker.js

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Latency tracker for real percentile computation
+ *
+ * All samples are stored for accurate percentile computation.
+ * Sorted cache is invalidated when new samples are added.
+ * Percentiles use linear interpolation between nearest values.
+ *
+ * Suitable for simulation-scale workloads (hundreds to low thousands of samples).
+ * For workloads exceeding ~100k samples, consider a streaming percentile
+ * algorithm (e.g., t-digest or HDR histogram).
+ */
+export class LatencyTracker {
+    samples = [];
+    sorted = null;
+    sum = 0;
+    /**
+     * Record a latency sample.
+     * @param latencyMs - Latency value in milliseconds
+     */
+    record(latencyMs) {
+        this.samples.push(latencyMs);
+        this.sum += latencyMs;
+        this.sorted = null;
+    }
+    /** Get the number of recorded samples. */
+    get count() {
+        return this.samples.length;
+    }
+    /** Get the average latency. */
+    get average() {
+        if (this.samples.length === 0)
+            return 0;
+        return this.sum / this.samples.length;
+    }
+    /**
+     * Compute a percentile value using linear interpolation.
+     * @param p - Percentile (0-100), e.g., 50, 95, 99
+     * @returns The latency value at the given percentile, or 0 if no samples
+     */
+    getPercentile(p) {
+        if (this.samples.length === 0)
+            return 0;
+        if (this.samples.length === 1)
+            return this.samples[0] ?? 0;
+        const sorted = this.getSorted();
+        const index = (p / 100) * (sorted.length - 1);
+        const lower = Math.floor(index);
+        const upper = Math.ceil(index);
+        if (lower === upper)
+            return sorted[lower] ?? 0;
+        const fraction = index - lower;
+        return (sorted[lower] ?? 0) * (1 - fraction) + (sorted[upper] ?? 0) * fraction;
+    }
+    /**
+     * Get a latency snapshot compatible with SimulationMetrics fields.
+     */
+    getLatencySnapshot() {
+        return {
+            avgLatencyMs: this.average,
+            p50LatencyMs: this.getPercentile(50),
+            p95LatencyMs: this.getPercentile(95),
+            p99LatencyMs: this.getPercentile(99),
+        };
+    }
+    /** Reset all tracked samples. */
+    reset() {
+        this.samples.length = 0;
+        this.sorted = null;
+        this.sum = 0;
+    }
+    getSorted() {
+        this.sorted ??= [...this.samples].sort((a, b) => a - b);
+        return this.sorted;
+    }
+}
+//# sourceMappingURL=latency-tracker.js.map

package/dist/framework/execution/latency-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"latency-tracker.js","sourceRoot":"","sources":["../../../src/framework/execution/latency-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,OAAO,cAAc;IACjB,OAAO,GAAa,EAAE,CAAC;IACvB,MAAM,GAAoB,IAAI,CAAC;IAC/B,GAAG,GAAG,CAAC,CAAC;IAEhB;;;OAGG;IACH,MAAM,CAAC,SAAiB;QACtB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC7B,IAAI,CAAC,GAAG,IAAI,SAAS,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,0CAA0C;IAC1C,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,+BAA+B;IAC/B,IAAI,OAAO;QACT,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IACxC,CAAC;IAED;;;;OAIG;IACH,aAAa,CAAC,CAAS;QACrB,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACxC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAE3D,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAE/B,IAAI,KAAK,KAAK,KAAK;YAAE,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAE/C,MAAM,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAC;QAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,QAAQ,CAAC;IACjF,CAAC;IAED;;OAEG;IACH,kBAAkB;QAMhB,OAAO;YACL,YAAY,EAAE,IAAI,CAAC,OAAO;YAC1B,YAAY,EAAE,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;YACpC,YAAY,EAAE,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;YACpC,YAAY,EAAE,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;SACrC,CAAC;IACJ,CAAC;IAED,iCAAiC;IACjC,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;IACf,CAAC;IAEO,SAAS;QACf,IAAI,CAAC,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACxD,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF"}

package/dist/framework/execution/run-load-window.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Shared load-window driver used by the load and chaos kinds.
+ *
+ * Both kinds run a tick-driven RPS loop with ramp-up and latency tracking that
+ * issues **real requests** against a user-supplied {@link Target}: each request
+ * is awaited, timed, and classified from resolve (success) / throw (failure).
+ * Requests are dispatched concurrently up to the workload's in-flight cap so
+ * real latency overlaps instead of serializing.
+ *
+ * The driver is fault-agnostic. The chaos kind injects faults by wrapping its
+ * `Target` with the fault model (`fault-model.ts`) before handing it here — the
+ * driver just drives whatever `Target` it is given. Centralising the loop here
+ * keeps both kinds on one real driver (the Template Method shape: kinds supply
+ * the `Target`, the framework owns the loop lifecycle).
+ */
+import type { Target } from './target.js';
+import type { SimulationMetrics } from '../../types/base-types.js';
+import type { ScenarioExecutionContext } from '../../types/framework-types.js';
+import type { Workload } from '../../types/workload.js';
+/** Subset of a kind config the load-window driver actually consumes. */
+export interface LoadWindowConfig {
+    readonly workload: Workload;
+}
+/** Options passed to `runLoadWindow`. */
+export interface RunLoadWindowOptions {
+    /** Duration the window runs for, in milliseconds. */
+    readonly windowMs: number;
+    /** The (possibly fault-decorated) target driven once per request. */
+    readonly target: Target;
+}
+/** Aggregated outcome of a single load window. */
+export interface LoadWindowResult {
+    readonly metrics: SimulationMetrics;
+}
+/**
+ * Run a single load-style window against a real `Target`.
+ *
+ * Per request: time the awaited `target` call, count success on resolve and
+ * failure on throw (including aborts), and record the measured latency. The
+ * driver paces toward `workload.rps` with optional ramp-up and never exceeds
+ * `resolveConcurrency(workload)` in-flight requests. In-flight requests are
+ * drained before the latency snapshot is taken so it reflects the full window.
+ */
+export declare function runLoadWindow(config: LoadWindowConfig, context: ScenarioExecutionContext, options: RunLoadWindowOptions): Promise<LoadWindowResult>;
+//# sourceMappingURL=run-load-window.d.ts.map

package/dist/framework/execution/run-load-window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-load-window.d.ts","sourceRoot":"","sources":["../../../src/framework/execution/run-load-window.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAMxD,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B;AAED,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACrC;AAgFD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CAmD3B"}

package/dist/framework/execution/run-load-window.js

@@ -0,0 +1,136 @@
+// @fitness-ignore-file detached-promises -- the driver intentionally dispatches in-flight requests and tracks them in a Set, draining via Promise.allSettled
+/**
+ * @fileoverview Shared load-window driver used by the load and chaos kinds.
+ *
+ * Both kinds run a tick-driven RPS loop with ramp-up and latency tracking that
+ * issues **real requests** against a user-supplied {@link Target}: each request
+ * is awaited, timed, and classified from resolve (success) / throw (failure).
+ * Requests are dispatched concurrently up to the workload's in-flight cap so
+ * real latency overlaps instead of serializing.
+ *
+ * The driver is fault-agnostic. The chaos kind injects faults by wrapping its
+ * `Target` with the fault model (`fault-model.ts`) before handing it here — the
+ * driver just drives whatever `Target` it is given. Centralising the loop here
+ * keeps both kinds on one real driver (the Template Method shape: kinds supply
+ * the `Target`, the framework owns the loop lifecycle).
+ */
+import { resolveConcurrency } from '../../types/workload.js';
+import { LatencyTracker } from './latency-tracker.js';
+// =============================================================================
+// IMPLEMENTATION
+// =============================================================================
+const TICK_INTERVAL_MS = 100;
+function createMetrics() {
+    return {
+        totalRequests: 0,
+        successfulRequests: 0,
+        failedRequests: 0,
+        avgLatencyMs: 0,
+        p50LatencyMs: 0,
+        p95LatencyMs: 0,
+        p99LatencyMs: 0,
+        errorsGenerated: 0,
+    };
+}
+function sleepTick(intervalMs, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const timeout = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, intervalMs);
+        const onAbort = () => {
+            clearTimeout(timeout);
+            resolve();
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/** Issue one request: time it, classify resolve/throw, track it in-flight. */
+function dispatchRequest(state) {
+    const { target, context, metrics, latencyTracker, inFlight } = state;
+    const t0 = Date.now();
+    metrics.totalRequests++;
+    const run = (async () => {
+        try {
+            await target({ signal: context.abortSignal, correlationId: context.correlationId });
+            metrics.successfulRequests++;
+        }
+        catch {
+            metrics.failedRequests++;
+            metrics.errorsGenerated++;
+        }
+        finally {
+            latencyTracker.record(Date.now() - t0);
+        }
+    })();
+    inFlight.add(run);
+    void run.finally(() => inFlight.delete(run));
+}
+/** Block until fewer than `cap` requests are in flight (or the run aborts). */
+async function awaitBelowCap(inFlight, cap, signal) {
+    while (inFlight.size >= cap && !signal.aborted) {
+        // @fitness-ignore-next-line performance-anti-patterns -- back-pressure gate: blocks until the fastest in-flight request settles to free a concurrency slot; parallelizing defeats the cap
+        await Promise.race(inFlight);
+    }
+}
+/**
+ * Run a single load-style window against a real `Target`.
+ *
+ * Per request: time the awaited `target` call, count success on resolve and
+ * failure on throw (including aborts), and record the measured latency. The
+ * driver paces toward `workload.rps` with optional ramp-up and never exceeds
+ * `resolveConcurrency(workload)` in-flight requests. In-flight requests are
+ * drained before the latency snapshot is taken so it reflects the full window.
+ */
+export async function runLoadWindow(config, context, options) {
+    const { workload } = config;
+    const targetRps = workload.rps;
+    const maxInFlight = resolveConcurrency(workload);
+    const metrics = createMetrics();
+    const latencyTracker = new LatencyTracker();
+    const inFlight = new Set();
+    const state = {
+        target: options.target,
+        context,
+        metrics,
+        latencyTracker,
+        inFlight,
+    };
+    const start = Date.now();
+    const rampUpMs = (workload.rampUp ?? 0) * 1000;
+    let fractionalRequests = 0; // carry for low/non-integer rps across ticks
+    while (Date.now() - start < options.windowMs && !context.abortSignal.aborted) {
+        const elapsed = Date.now() - start;
+        const rampUpProgress = rampUpMs > 0 ? Math.min(1, elapsed / rampUpMs) : 1;
+        // Use fractional accumulator so low rps (e.g. 5) or non-integer rates don't floor to 0 requests
+        // every tick. Each tick we add the due fraction; floor gives whole requests this tick,
+        // remainder carries forward. This fixes under-delivery / zero-work for rps < 10 (100ms tick).
+        // (See AUDIT-FINDINGS and original correctness audit.)
+        const dueThisTick = (targetRps * rampUpProgress) / (1000 / TICK_INTERVAL_MS);
+        fractionalRequests += dueThisTick;
+        const requestsThisTick = Math.floor(fractionalRequests);
+        fractionalRequests -= requestsThisTick;
+        for (let i = 0; i < requestsThisTick; i++) {
+            // Backpressure: block until below the in-flight cap, which paces RPS
+            // toward what latency + concurrency actually allow.
+            await awaitBelowCap(inFlight, maxInFlight, context.abortSignal);
+            if (context.abortSignal.aborted)
+                break;
+            dispatchRequest(state);
+        }
+        await sleepTick(TICK_INTERVAL_MS, context.abortSignal);
+    }
+    // Drain any still-in-flight requests so the latency snapshot covers them.
+    await Promise.allSettled(inFlight);
+    const snapshot = latencyTracker.getLatencySnapshot();
+    metrics.avgLatencyMs = snapshot.avgLatencyMs;
+    metrics.p50LatencyMs = snapshot.p50LatencyMs;
+    metrics.p95LatencyMs = snapshot.p95LatencyMs;
+    metrics.p99LatencyMs = snapshot.p99LatencyMs;
+    return { metrics };
+}
+//# sourceMappingURL=run-load-window.js.map

package/dist/framework/execution/run-load-window.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-load-window.js","sourceRoot":"","sources":["../../../src/framework/execution/run-load-window.ts"],"names":[],"mappings":"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"}

package/dist/framework/execution/scenario-aborted-error.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview ScenarioAbortedError - extracted to break circular dependency
+ * between action-handlers.ts and execution-engine.ts.
+ */
+import { SystemError } from '@opensip-cli/core';
+/**
+ * Error thrown when a scenario is aborted via AbortSignal.
+ * This error must ALWAYS be re-thrown, never swallowed.
+ */
+export declare class ScenarioAbortedError extends SystemError {
+    readonly scenarioId: string | undefined;
+    constructor(scenarioId?: string);
+}
+//# sourceMappingURL=scenario-aborted-error.d.ts.map

package/dist/framework/execution/scenario-aborted-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario-aborted-error.d.ts","sourceRoot":"","sources":["../../../src/framework/execution/scenario-aborted-error.ts"],"names":[],"mappings":"AACA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,WAAW;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE5B,UAAU,CAAC,EAAE,MAAM;CAUhC"}

package/dist/framework/execution/scenario-aborted-error.js

@@ -0,0 +1,24 @@
+// @fitness-ignore-file project-readme-existence -- internal module, not a package root
+/**
+ * @fileoverview ScenarioAbortedError - extracted to break circular dependency
+ * between action-handlers.ts and execution-engine.ts.
+ */
+import { SystemError } from '@opensip-cli/core';
+/**
+ * Error thrown when a scenario is aborted via AbortSignal.
+ * This error must ALWAYS be re-thrown, never swallowed.
+ */
+export class ScenarioAbortedError extends SystemError {
+    scenarioId;
+    constructor(scenarioId) {
+        super(scenarioId ? `Scenario ${scenarioId} was aborted` : 'Scenario was aborted', {
+            code: 'SIMULATION.SCENARIO.ABORTED',
+            severity: 'medium',
+            metadata: scenarioId ? { scenarioId } : {},
+        });
+        this.name = 'ScenarioAbortedError';
+        this.scenarioId = scenarioId;
+        Object.setPrototypeOf(this, ScenarioAbortedError.prototype);
+    }
+}
+//# sourceMappingURL=scenario-aborted-error.js.map

package/dist/framework/execution/scenario-aborted-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario-aborted-error.js","sourceRoot":"","sources":["../../../src/framework/execution/scenario-aborted-error.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,WAAW;IAC1C,UAAU,CAAqB;IAExC,YAAY,UAAmB;QAC7B,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,YAAY,UAAU,cAAc,CAAC,CAAC,CAAC,sBAAsB,EAAE;YAChF,IAAI,EAAE,6BAA6B;YACnC,QAAQ,EAAE,QAAQ;YAClB,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE;SAC3C,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAC9D,CAAC;CACF"}

package/dist/framework/execution/target.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview `Target` — the BYO (bring-your-own) seam for the simulation
+ * harness.
+ *
+ * A `Target` is the single outside-world contract: the load-window driver calls
+ * it once per request. It is intentionally protocol-agnostic — an `async`
+ * function that **resolves on success and throws on failure**. The harness
+ * measures wall-clock latency around the call and classifies the outcome from
+ * resolve/throw. HTTP users reach for the `httpTarget()` helper, but any async
+ * function (gRPC, in-process, a shell-out) is a valid target.
+ *
+ * A well-behaved target passes `ctx.signal` to its I/O and rejects when the
+ * signal aborts (scenario abort + `abort` faults rely on this). The fault model
+ * additionally guarantees an `abort` fault counts as a failure even for a
+ * target that ignores the signal (see `fault-model.ts`).
+ *
+ * This is a leaf module: it imports nothing from the type or runtime layers so
+ * the driver, fault model, and helpers can depend on it without cycles.
+ */
+/** Context handed to a `Target` for each request. */
+export interface TargetContext {
+    /** Abort signal for the request; aborts on scenario abort or an `abort` fault. */
+    readonly signal: AbortSignal;
+    /** Correlation id for the enclosing scenario run. */
+    readonly correlationId: string;
+}
+/**
+ * A user-supplied target the driver invokes once per request.
+ *
+ * Resolve = the request succeeded. Throw (or reject on `ctx.signal` abort) =
+ * the request failed. The harness times the call and never inspects a return
+ * value, so `Promise<void>` is the whole contract.
+ */
+export type Target = (ctx: TargetContext) => Promise<void>;
+//# sourceMappingURL=target.d.ts.map

package/dist/framework/execution/target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../../../src/framework/execution/target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/framework/execution/target.js

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview `Target` — the BYO (bring-your-own) seam for the simulation
+ * harness.
+ *
+ * A `Target` is the single outside-world contract: the load-window driver calls
+ * it once per request. It is intentionally protocol-agnostic — an `async`
+ * function that **resolves on success and throws on failure**. The harness
+ * measures wall-clock latency around the call and classifies the outcome from
+ * resolve/throw. HTTP users reach for the `httpTarget()` helper, but any async
+ * function (gRPC, in-process, a shell-out) is a valid target.
+ *
+ * A well-behaved target passes `ctx.signal` to its I/O and rejects when the
+ * signal aborts (scenario abort + `abort` faults rely on this). The fault model
+ * additionally guarantees an `abort` fault counts as a failure even for a
+ * target that ignores the signal (see `fault-model.ts`).
+ *
+ * This is a leaf module: it imports nothing from the type or runtime layers so
+ * the driver, fault model, and helpers can depend on it without cycles.
+ */
+export {};
+//# sourceMappingURL=target.js.map

package/dist/framework/execution/target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.js","sourceRoot":"","sources":["../../../src/framework/execution/target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/framework/registry.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Cross-kind scenario registry — per-RunScope.
+ *
+ * Each `RunScope` owns its own `Registry<RunnableScenario>` (Item 1 /
+ * D7 — tool subscopes via module augmentation).
+ * The simulation tool's `contributeScope` hook constructs a fresh registry
+ * per CLI invocation and attaches it to `scope.simulation.scenarios`.
+ *
+ * Built on the kernel's unified `Registry<T>` with
+ * `duplicatePolicy: 'silent-skip'` (re-importing the same scenario is a
+ * no-op) + `nameCollisionMode: 'throw'` (two different scenario ids
+ * sharing a name would corrupt the dual-key state). This is the same
+ * shape the legacy `IdNameTagRegistry` provided (which has been deleted).
+ *
+ * Public API:
+ *   - `createScenarioRegistry()`  — factory used by `contributeScope`.
+ *   - `currentScenarioRegistry()` — reads the scope-bound registry;
+ *                                   throws when called outside a scope
+ *                                   or when `simulation` subscope is
+ *                                   absent.
+ *   - `getRegisteredScenarios()` / `getScenario` / `getScenariosByTag` /
+ *     `getScenariosByKind` / `clearScenarioRegistry` — thin helpers that
+ *     route through the scope-bound registry.
+ */
+import { Registry } from '@opensip-cli/core';
+import type { RunnableScenario } from './runnable-scenario.js';
+import type { SimulationLoadState } from '../scope-augmentation.js';
+import type { ScenarioKind } from '../types/kind-types.js';
+/** Construct a fresh `ensureScenariosLoaded` lifecycle slot for a single `RunScope` (audit F1). */
+export declare function createSimulationLoadState(): SimulationLoadState;
+/**
+ * Read the current scope's simulation load state (`scope.simulation.load`).
+ * Throws when no scope/subscope is active — same contract as
+ * {@link currentScenarioRegistry}.
+ *
+ * @throws {Error} When called outside `runWithScope(...)`, or when the active
+ *   scope has no simulation subscope.
+ */
+export declare function currentSimulationLoadState(): SimulationLoadState;
+/** Construct a fresh scenario registry for a single `RunScope`. */
+export declare function createScenarioRegistry(): Registry<RunnableScenario>;
+/**
+ * Read the current scope's scenario registry. Throws when no scope is
+ * active or when the simulation subscope is missing — both indicate the
+ * caller is running outside the CLI's pre-action-hook (or the test
+ * fixture forgot to construct + enter a scope).
+ *
+ * @throws {Error} When called outside `runWithScope(...)`, or when the
+ *   active scope has no simulation subscope.
+ */
+export declare function currentScenarioRegistry(): Registry<RunnableScenario>;
+/** Get all registered scenarios from the current scope's registry. */
+export declare function getRegisteredScenarios(): Map<string, RunnableScenario>;
+/** Get a scenario by id or name from the current scope's registry. */
+export declare function getScenario(idOrName: string): RunnableScenario | undefined;
+/** Get scenarios filtered by tag (any kind). */
+export declare function getScenariosByTag(tag: string): readonly RunnableScenario[];
+/** Get scenarios filtered by kind. */
+export declare function getScenariosByKind(kind: ScenarioKind): RunnableScenario[];
+/**
+ * Clear the current scope's scenario registry. Used by tests, by host
+ * applications that need to swap the scenario set at runtime, and by
+ * recipe-reset code paths. The simulation engine's plugin loader
+ * re-populates it on the next load cycle.
+ */
+export declare function clearScenarioRegistry(): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/framework/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/framework/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,QAAQ,EAAgB,MAAM,mBAAmB,CAAC;AAE3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,mGAAmG;AACnG,wBAAgB,yBAAyB,IAAI,mBAAmB,CAE/D;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,IAAI,mBAAmB,CAUhE;AAED,mEAAmE;AACnE,wBAAgB,sBAAsB,IAAI,QAAQ,CAAC,gBAAgB,CAAC,CAQnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,IAAI,QAAQ,CAAC,gBAAgB,CAAC,CAmBpE;AAED,sEAAsE;AACtE,wBAAgB,sBAAsB,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAMtE;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAE1E;AAED,gDAAgD;AAChD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,gBAAgB,EAAE,CAE1E;AAED,sCAAsC;AACtC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,gBAAgB,EAAE,CAIzE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}