@chaos-maker/core 0.3.0 → 0.5.0

package/dist/types/index.d.ts

@@ -1,10 +1,39 @@
 import { ChaosMaker } from './ChaosMaker';
-import { ChaosConfig, CorruptionStrategy, NetworkFailureConfig, NetworkLatencyConfig, NetworkAbortConfig, NetworkCorruptionConfig, NetworkCorsConfig, NetworkConfig, UiAssaultConfig, UiConfig, WebSocketConfig, WebSocketDropConfig, WebSocketDelayConfig, WebSocketCorruptConfig, WebSocketCloseConfig, WebSocketDirection, WebSocketCorruptionStrategy } from './config';
+import { ChaosConfig, CorruptionStrategy, GraphQLOperationMatcher, NetworkFailureConfig, NetworkLatencyConfig, NetworkAbortConfig, NetworkCorruptionConfig, NetworkCorsConfig, NetworkConfig, NetworkRuleMatchers, RuleGroupAssignment, UiAssaultConfig, UiConfig, WebSocketConfig, WebSocketDropConfig, WebSocketDelayConfig, WebSocketCorruptConfig, WebSocketCloseConfig, WebSocketDirection, WebSocketCorruptionStrategy, SSEConfig, SSEDropConfig, SSEDelayConfig, SSECorruptConfig, SSECloseConfig, SSECorruptionStrategy, SSEEventTypeMatcher } from './config';
 import { ChaosConfigError } from './errors';
-import { validateConfig } from './validation';
+import { validateConfig, prepareChaosConfig, validateChaosConfig, VALIDATOR_BRAND_VERSION, type ValidateChaosConfigOptions, type PrepareChaosConfigOptions } from './validation';
 import { ChaosEvent, ChaosEventType, ChaosEventListener, ChaosEventEmitter } from './events';
 import { ChaosConfigBuilder } from './builder';
-import { presets } from './presets';
+import { presets, PresetRegistry, BUILT_IN_PRESETS, expandPresets } from './presets';
 import { createPrng, generateSeed } from './prng';
-export { ChaosMaker, ChaosConfigError, validateConfig, ChaosEventEmitter, ChaosConfigBuilder, presets, createPrng, generateSeed };
-export type { ChaosConfig, CorruptionStrategy, NetworkFailureConfig, NetworkLatencyConfig, NetworkAbortConfig, NetworkCorruptionConfig, NetworkCorsConfig, NetworkConfig, UiAssaultConfig, UiConfig, WebSocketConfig, WebSocketDropConfig, WebSocketDelayConfig, WebSocketCorruptConfig, WebSocketCloseConfig, WebSocketDirection, WebSocketCorruptionStrategy, ChaosEvent, ChaosEventType, ChaosEventListener };
+/** `validateChaosConfig` is the canonical structured validation entry. Layers
+ *  schema-version gating, brand-cache short-circuit, deprecation walk, and
+ *  custom validators on top of `prepareChaosConfig` (Zod pass 1 + preset
+ *  expansion + Zod pass 2). The `ChaosMaker` constructor and every adapter
+ *  call through it.
+ *
+ *  `prepareChaosConfig` is the lower-level primitive without the brand /
+ *  deprecation / customValidators layers; useful in advanced flows that
+ *  manage their own re-validation cadence.
+ *
+ *  `validateConfig` is the schema-only primitive — does NOT expand presets.
+ *  Use only for unit-test structural assertions. */
+export { ChaosMaker, ChaosConfigError, validateConfig, prepareChaosConfig, validateChaosConfig, VALIDATOR_BRAND_VERSION, ChaosEventEmitter, ChaosConfigBuilder, presets, PresetRegistry, BUILT_IN_PRESETS, expandPresets, createPrng, generateSeed };
+/** Internal: prebuilt Zod schema variants. Exported so the JSON-schema build
+ *  script can serialize the canonical strict variant. Application code should
+ *  call `validateChaosConfig` instead — the schemas are not the public
+ *  validation surface and may evolve without a version bump. */
+export { chaosConfigSchemaStrict, chaosConfigSchemaPassthrough } from './validation';
+export type { ValidateChaosConfigOptions, PrepareChaosConfigOptions };
+export type { ValidationIssue, ValidationIssueCode, RuleType, CustomRuleValidator, CustomValidatorMap, DeprecationEntry } from './validation-types';
+export type { Preset, PresetConfigSlice } from './presets';
+export { SW_BRIDGE_SOURCE } from './sw-bridge-source';
+export { extractGraphQLOperation, parseOperationFromQueryString, operationNameMatches } from './graphql';
+export { serializeForTransport, deserializeForTransport } from './transport';
+export { DEFAULT_GROUP_NAME, RuleGroupRegistry } from './groups';
+export { Logger, normalizeDebugOption, formatDebugMessage, buildRuleIdMap } from './debug';
+export type { RuleGroup, RuleGroupConfig } from './groups';
+export type { GraphQLExtractResult, GraphQLRuleOutcome } from './graphql';
+export type { DebugOptions, ChaosDebugStage, RuleIdEntry } from './debug';
+export type { ChaosLifecyclePhase } from './events';
+export type { ChaosConfig, CorruptionStrategy, GraphQLOperationMatcher, NetworkFailureConfig, NetworkLatencyConfig, NetworkAbortConfig, NetworkCorruptionConfig, NetworkCorsConfig, NetworkConfig, NetworkRuleMatchers, RuleGroupAssignment, UiAssaultConfig, UiConfig, WebSocketConfig, WebSocketDropConfig, WebSocketDelayConfig, WebSocketCorruptConfig, WebSocketCloseConfig, WebSocketDirection, WebSocketCorruptionStrategy, SSEConfig, SSEDropConfig, SSEDelayConfig, SSECorruptConfig, SSECloseConfig, SSECorruptionStrategy, SSEEventTypeMatcher, ChaosEvent, ChaosEventType, ChaosEventListener };

package/dist/types/interceptors/domAssailant.d.ts

@@ -1,3 +1,4 @@
 import { UiConfig } from '../config';
 import { ChaosEventEmitter } from '../events';
-export declare function attachDomAssailant(config: UiConfig, random: () => number, emitter?: ChaosEventEmitter): MutationObserver;
+import type { RuleGroupRegistry } from '../groups';
+export declare function attachDomAssailant(config: UiConfig, random: () => number, emitter?: ChaosEventEmitter, groups?: RuleGroupRegistry): MutationObserver;

package/dist/types/interceptors/eventSource.d.ts

@@ -0,0 +1,42 @@
+/**
+ * EventSource (Server-Sent Events) chaos interceptor.
+ *
+ * Mirrors the WebSocket interceptor's wrapper-constructor strategy: replace
+ * `globalThis.EventSource` with a chaos wrapper that owns a hidden real
+ * `EventSource` instance, intercepts inbound `MessageEvent`s on the capture
+ * phase via `stopImmediatePropagation`, and re-dispatches mutated payloads.
+ *
+ * Design notes:
+ * - SSE is inbound-only (the spec defines no client → server channel beyond
+ *   the initial GET), so direction/payloadType fields are absent vs. WS.
+ * - `event.data` is always a string per the spec — corruption strategies
+ *   reuse the four text strategies from network/WS chaos.
+ * - Counting (onNth/everyNth/afterN) is per-rule, per-event, identical to WS.
+ * - Per-rule ordering on a matched event: drop → corrupt → delay. A dropped
+ *   event short-circuits the rest.
+ * - Close chaos dispatches an `error` event then calls `.close()` on the
+ *   underlying EventSource. Delivery of `error` mirrors what browsers do
+ *   when the upstream connection drops; the app's reconnection logic (if any)
+ *   re-runs the original `new EventSource(url)` path, so a fresh wrapper is
+ *   created and chaos continues.
+ * - On `uninstall()`, every pending delay timer is cleared and an
+ *   `sse:drop` is emitted for it with `reason: 'stop-during-delay'`. Pending
+ *   close timers cancel silently (they had not fired anything yet).
+ */
+import { SSEConfig } from '../config';
+import { ChaosEventEmitter } from '../events';
+import type { RuleGroupRegistry } from '../groups';
+export interface EventSourceLikeStatic {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSED: 2;
+    new (url: string | URL, init?: EventSourceInit): EventSource;
+    prototype: EventSource;
+}
+export interface EventSourcePatchHandle {
+    /** Wrapped EventSource constructor suitable for `globalThis.EventSource = …`. */
+    readonly Wrapped: typeof EventSource;
+    /** Cancel pending timers and disarm wrapped instances. Call on ChaosMaker.stop(). */
+    uninstall(): void;
+}
+export declare function patchEventSource(OriginalEventSource: EventSourceLikeStatic, config: SSEConfig, emitter: ChaosEventEmitter, random: () => number, counters: Map<object, number>, groups?: RuleGroupRegistry): EventSourcePatchHandle;

package/dist/types/interceptors/networkFetch.d.ts

@@ -1,3 +1,4 @@
 import { NetworkConfig } from '../config';
+import type { RuleGroupRegistry } from '../groups';
 import { ChaosEventEmitter } from '../events';
-export declare function patchFetch(originalFetch: typeof window.fetch, config: NetworkConfig, random: () => number, emitter?: ChaosEventEmitter, counters?: Map<object, number>): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export declare function patchFetch(originalFetch: typeof globalThis.fetch, config: NetworkConfig, random: () => number, emitter?: ChaosEventEmitter, counters?: Map<object, number>, groups?: RuleGroupRegistry): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;

package/dist/types/interceptors/networkXHR.d.ts

@@ -1,4 +1,5 @@
 import { NetworkConfig } from '../config';
+import type { RuleGroupRegistry } from '../groups';
 import { ChaosEventEmitter } from '../events';
-export declare function patchXHR(originalXhrSend: (body?: Document | XMLHttpRequestBodyInit) => void, config: NetworkConfig, random: () => number, emitter?: ChaosEventEmitter, counters?: Map<object, number>): (this: XMLHttpRequest, body?: Document | XMLHttpRequestBodyInit) => void;
+export declare function patchXHR(originalXhrSend: (body?: Document | XMLHttpRequestBodyInit) => void, config: NetworkConfig, random: () => number, emitter?: ChaosEventEmitter, counters?: Map<object, number>, groups?: RuleGroupRegistry): (this: XMLHttpRequest, body?: Document | XMLHttpRequestBodyInit) => void;
 export declare function patchXHROpen(originalXhrOpen: (method: string, url: string | URL) => void): (this: XMLHttpRequest, method: string, url: string | URL) => void;

package/dist/types/interceptors/websocket.d.ts

@@ -2,7 +2,7 @@
  * WebSocket chaos interceptor.
  *
  * Design decisions (see V2_PHASE3_WEBSOCKET_PLAN.md §4, §9):
- * - Patch `window.WebSocket` with a wrapper constructor. Real socket is returned
+ * - Patch `globalThis.WebSocket` with a wrapper constructor. Real socket is returned
  *   so `instanceof WebSocket` continues to work. `.send` is overridden on the
  *   instance; inbound messages are intercepted via a listener installed *before*
  *   user code runs.
@@ -21,10 +21,11 @@
  */
 import { WebSocketConfig } from '../config';
 import { ChaosEventEmitter } from '../events';
+import type { RuleGroupRegistry } from '../groups';
 export interface WebSocketPatchHandle {
-    /** Wrapped WebSocket constructor suitable for `window.WebSocket = …`. */
+    /** Wrapped WebSocket constructor suitable for `globalThis.WebSocket = …`. */
     readonly Wrapped: typeof WebSocket;
     /** Clear all pending delay timers and emit drop events for them. Call on ChaosMaker.stop(). */
     uninstall(): void;
 }
-export declare function patchWebSocket(OriginalWebSocket: typeof WebSocket, config: WebSocketConfig, emitter: ChaosEventEmitter, random: () => number, counters: Map<object, number>): WebSocketPatchHandle;
+export declare function patchWebSocket(OriginalWebSocket: typeof WebSocket, config: WebSocketConfig, emitter: ChaosEventEmitter, random: () => number, counters: Map<object, number>, groups?: RuleGroupRegistry): WebSocketPatchHandle;

package/dist/types/presets.d.ts

@@ -1,2 +1,63 @@
-import { ChaosConfig } from './config';
-export declare const presets: Readonly<Record<string, ChaosConfig>>;
+import type { ChaosConfig } from './config';
+/** ChaosConfig slice a preset is allowed to carry. Auto-includes any new
+ *  rule category added to ChaosConfig — the `Omit` is bounded to fields that
+ *  are explicitly forbidden inside a preset (`presets`, `customPresets`,
+ *  `seed`, `debug`). */
+export type PresetConfigSlice = Omit<ChaosConfig, 'presets' | 'customPresets' | 'seed' | 'debug' | 'schemaVersion'>;
+/** A named preset packaged for registry registration. */
+export interface Preset {
+    readonly name: string;
+    readonly config: PresetConfigSlice;
+}
+/** All built-in presets including kebab aliases.
+ *  Aliases are EXTRA registry entries pointing at the SAME config object
+ *  identity as the camelCase entry — so
+ *  `registry.get('slow-api') === presets.slowNetwork`.
+ *
+ *  Both the array AND each `{ name, config }` descriptor are frozen so that
+ *  `BUILT_IN_PRESETS[0].name = 'x'` or `BUILT_IN_PRESETS[0].config = {}` cannot
+ *  poison future `PresetRegistry` constructions. Configs are already deep-
+ *  frozen above, so the descriptor freeze is the missing layer. */
+export declare const BUILT_IN_PRESETS: ReadonlyArray<Preset>;
+/** Per-instance registry of presets. Constructor seeds the built-ins
+ *  by default; pass an empty iterable to start from scratch. The slice shape
+ *  is type-enforced for built-ins and Zod-validated for `customPresets`, so
+ *  `register` does not re-check structure. */
+export declare class PresetRegistry {
+    private map;
+    constructor(initial?: Iterable<Preset>);
+    register(preset: Preset): void;
+    registerAll(entries: Record<string, PresetConfigSlice> | undefined): void;
+    has(name: string): boolean;
+    get(name: string): PresetConfigSlice;
+    list(): string[];
+}
+/** Expand `config.presets` against `registry`. Identity contract:
+ *
+ *   - ALWAYS returns a fresh `ChaosConfig`. Callers own the returned object
+ *     and may mutate it without affecting the input. Built-in slices stay
+ *     deep-frozen because each preset is deep-cloned at append time.
+ *   - The output ALWAYS has `presets` and `customPresets` stripped, even if
+ *     `presets[]` was empty. Prevents stale `customPresets` from leaking into
+ *     the post-expansion config.
+ *   - Append order: preset rules first (in the order they appear in
+ *     `presets[]`), user rules last. Same rule for `groups`.
+ *   - Throws when a name in `presets[]` is not registered. Plain `Error` —
+ *     `prepareChaosConfig` wraps to `ChaosConfigError`.
+ *
+ *  Defensive deduplication on `presets[]` runs here as well as in the Zod
+ *  transform, because `expandPresets` is exported and a contributor could
+ *  call it directly on an un-validated config. */
+export declare function expandPresets(config: ChaosConfig, registry: PresetRegistry): ChaosConfig;
+/** Backward-compat: the v0.4.0 frozen-record export. **CamelCase keys ONLY.**
+ *  kebab aliases (`slow-api`, `flaky-api`, `offline-mode`,
+ *  `high-latency`) live exclusively on `PresetRegistry` — they are NOT keys
+ *  on this record. By design:
+ *
+ *    presets['slow-api']  === undefined
+ *    presets.slowNetwork  === new PresetRegistry().get('slow-api')   // same identity
+ *    presets.slowNetwork  === new PresetRegistry().get('slowNetwork')
+ *
+ *  Use the camelCase key when reading from this record; use the registry (or
+ *  the declarative `presets: ['slow-api']` config field) for kebab lookups. */
+export declare const presets: Readonly<Record<string, PresetConfigSlice>>;

package/dist/types/sw-bridge-source.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Browser-side bridge installed into the page by each adapter (Playwright /
+ * Cypress / WDIO / Puppeteer) to talk to the Service-Worker chaos engine.
+ *
+ * This is a string because it is injected via `addInitScript`, `eval` or a
+ * `<script>` tag — *not* imported as a module. Adapters are Node-side, but
+ * this source executes in the AUT window.
+ *
+ * Exposes `window.__chaosMakerSWBridge`:
+ *  - `apply(cfg, timeoutMs)` — post config over MessageChannel, wait for ack.
+ *  - `stop(timeoutMs)` — stop chaos in the SW.
+ *  - `toggleGroup(name, enabled, timeoutMs)` — flip a rule group inside the SW
+ *    via `__chaosMakerToggleGroup`; resolves on ack with no engine restart.
+ *  - `getLocalLog()` / `clearLocalLog()` — page-side buffered event log.
+ *  - `getRemoteLog(timeoutMs)` — fetch SW's in-memory log.
+ *
+ * The bridge auto-wires a `controllerchange` listener so SW updates inherit
+ * the most recent config. Install is idempotent.
+ */
+export declare const SW_BRIDGE_SOURCE = "\n(function installChaosMakerSWBridge() {\n  if (typeof window === 'undefined') return;\n  if (window.__chaosMakerSWBridgeInstalled) return;\n  window.__chaosMakerSWBridgeInstalled = true;\n\n  var log = [];\n  var lastConfig = null;\n\n  function addSwListeners() {\n    if (!('serviceWorker' in navigator)) return;\n    navigator.serviceWorker.addEventListener('message', function (evt) {\n      var data = evt && evt.data;\n      if (data && data.__chaosMakerSWEvent && data.event) {\n        log.push(data.event);\n      }\n    });\n    navigator.serviceWorker.addEventListener('controllerchange', function () {\n      if (lastConfig) {\n        postConfig(lastConfig, 5000).catch(function (err) {\n          try { console.warn('[chaos-maker] re-apply after controllerchange failed', err); } catch (_) {}\n        });\n      }\n    });\n  }\n\n  function waitForController(timeoutMs) {\n    return new Promise(function (resolve, reject) {\n      if (!('serviceWorker' in navigator)) {\n        reject(new Error('[chaos-maker] service worker API not available on this page'));\n        return;\n      }\n      var start = Date.now();\n      (function poll() {\n        if (navigator.serviceWorker.controller) {\n          resolve(navigator.serviceWorker.controller);\n          return;\n        }\n        if (Date.now() - start >= timeoutMs) {\n          reject(new Error('[chaos-maker] no SW controller after ' + timeoutMs + 'ms \u2014 did you register the SW?'));\n          return;\n        }\n        setTimeout(poll, 50);\n      })();\n    });\n  }\n\n  function postViaPort(controller, message, timeoutMs) {\n    return new Promise(function (resolve, reject) {\n      var channel = new MessageChannel();\n      var settled = false;\n      var timer = setTimeout(function () {\n        if (settled) return;\n        settled = true;\n        try { channel.port1.close(); } catch (_) {}\n        reject(new Error('[chaos-maker] SW ack timeout after ' + timeoutMs + 'ms'));\n      }, timeoutMs);\n      channel.port1.onmessage = function (evt) {\n        if (settled) return;\n        settled = true;\n        clearTimeout(timer);\n        resolve(evt && evt.data);\n      };\n      controller.postMessage(message, [channel.port2]);\n    });\n  }\n\n  function postConfig(cfg, timeoutMs) {\n    return waitForController(timeoutMs).then(function (ctrl) {\n      return postViaPort(ctrl, { __chaosMakerConfig: cfg }, timeoutMs);\n    });\n  }\n\n  window.__chaosMakerSWBridge = {\n    apply: function (cfg, timeoutMs) {\n      // Defensive: page-side adapters validate before calling apply. The\n      // page-side bundle deliberately excludes Zod, so a null/primitive/\n      // array/wildly-wrong payload throws here instead of silently posting\n      // garbage to the SW. `typeof [] === 'object'` so reject arrays too.\n      if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) {\n        return Promise.reject(new Error('[chaos-maker] bridge.apply: config must be an object'));\n      }\n      // Stash cfg BEFORE awaiting ack \u2014 intentional. If the first ack times\n      // out (e.g. SW still installing), the controllerchange listener above\n      // will retry with this config once the new SW claims the page. Caller\n      // still sees the rejection from this attempt and can re-throw.\n      lastConfig = cfg;\n      return postConfig(cfg, timeoutMs).then(function (ack) {\n        return { seed: ack && typeof ack.seed === 'number' ? ack.seed : null };\n      });\n    },\n    stop: function (timeoutMs) {\n      lastConfig = null;\n      if (!('serviceWorker' in navigator) || !navigator.serviceWorker.controller) {\n        return Promise.resolve({ running: false });\n      }\n      return postViaPort(navigator.serviceWorker.controller, { __chaosMakerStop: true }, timeoutMs);\n    },\n    toggleGroup: function (name, enabled, timeoutMs) {\n      if (!('serviceWorker' in navigator) || !navigator.serviceWorker.controller) {\n        return Promise.reject(new Error('[chaos-maker] no SW controller \u2014 call injectSWChaos before toggleGroup'));\n      }\n      var t = (typeof timeoutMs === 'number' && timeoutMs > 0) ? timeoutMs : 2000;\n      return postViaPort(\n        navigator.serviceWorker.controller,\n        { __chaosMakerToggleGroup: { name: String(name), enabled: !!enabled } },\n        t,\n      );\n    },\n    getLocalLog: function () { return log.slice(); },\n    clearLocalLog: function () { log.length = 0; },\n    getRemoteLog: function (timeoutMs) {\n      if (!('serviceWorker' in navigator) || !navigator.serviceWorker.controller) {\n        return Promise.resolve([]);\n      }\n      return postViaPort(navigator.serviceWorker.controller, { __chaosMakerGetLog: true }, timeoutMs)\n        .then(function (reply) {\n          return (reply && Array.isArray(reply.log)) ? reply.log : [];\n        });\n    },\n  };\n\n  addSwListeners();\n})();\n";

package/dist/types/sw.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Service Worker chaos entry point.
+ *
+ * Loaded into the user's service-worker script (classic `importScripts(…)` or
+ * module-worker `import { installChaosSW }`), this module patches
+ * `self.fetch` + `self.WebSocket` using the same interceptor engine that
+ * powers page-context chaos. Config is delivered from the page via
+ * `postMessage` and acked through a `MessageChannel` transferred by the
+ * adapter helper. Every chaos event is broadcast to controlled clients so
+ * tests can read a unified log on the page side.
+ *
+ * Deliberately excluded from this bundle: Zod validation, UI DOM assailant,
+ * the public `ChaosMaker` class, and the builder — all page-side concerns.
+ * The page-side adapter helpers validate config before postMessage, so the
+ * SW bundle stays small enough to ship to production service workers.
+ */
+import type { ChaosConfig } from './config';
+import type { ChaosEvent } from './events';
+/** Message sent by page → SW to configure chaos. */
+export interface ChaosSWConfigMessage {
+    __chaosMakerConfig: ChaosConfig;
+}
+/** Message sent by page → SW to stop chaos and restore fetch/WebSocket. */
+export interface ChaosSWStopMessage {
+    __chaosMakerStop: true;
+}
+/** Message sent by page → SW to read the accumulated event log. */
+export interface ChaosSWGetLogMessage {
+    __chaosMakerGetLog: true;
+}
+/** Message sent by page → SW to clear the accumulated event log. */
+export interface ChaosSWClearLogMessage {
+    __chaosMakerClearLog: true;
+}
+/** Message sent by page -> SW to toggle a rule group without restarting chaos. */
+export interface ChaosSWToggleGroupMessage {
+    __chaosMakerToggleGroup: {
+        name: string;
+        enabled: boolean;
+    };
+}
+/** Ack sent SW → port (or broadcast) after a config / stop message lands. */
+export interface ChaosSWAck {
+    __chaosMakerAck: true;
+    seed?: number;
+    running: boolean;
+}
+/** Log payload sent SW → port (or broadcast) in response to getLog. */
+export interface ChaosSWLogReply {
+    __chaosMakerLog: true;
+    log: ChaosEvent[];
+}
+/** Event broadcast SW → all controlled clients for every chaos decision. */
+export interface ChaosSWEventMessage {
+    __chaosMakerSWEvent: true;
+    event: ChaosEvent;
+}
+export interface InstallChaosSWOptions {
+    /**
+     * How the SW receives its chaos config.
+     *
+     * - `'message'` (default) — wait for a `postMessage({ __chaosMakerConfig: … })`
+     *   from the page. Typically paired with a `MessageChannel` for ack.
+     * - `'self-global'` — read `self.__CHAOS_CONFIG__` synchronously. Useful when
+     *   the SW script is served with the config baked in (e.g. query-string).
+     */
+    source?: 'message' | 'self-global';
+    /** Max entries buffered in the SW-side log. Defaults to 2000. */
+    maxLogEntries?: number;
+}
+export interface SWChaosHandle {
+    /** True while a config is installed and `self.fetch` is patched. */
+    isRunning(): boolean;
+    /** Seed used by the active PRNG, or null if no config is installed. */
+    getSeed(): number | null;
+    /** Snapshot of chaos events emitted inside the SW since install. */
+    getLog(): ChaosEvent[];
+    /** Clear the in-SW log buffer. Does not clear already-delivered page-side events. */
+    clearLog(): void;
+    /** Stop chaos + remove the message listener. Restores `self.fetch`. */
+    uninstall(): void;
+}
+/**
+ * Install Service-Worker chaos. Listens for config via `postMessage`,
+ * patches `self.fetch` (and `self.WebSocket` when configured), and
+ * broadcasts every chaos event to all controlled clients so the test
+ * runner's page-side helper can build a unified event log.
+ *
+ * Idempotent: calling more than once returns the existing handle.
+ *
+ * @example Classic SW (typical user integration — one line)
+ * ```js
+ * // user's sw.js
+ * importScripts('/vendor/chaos-maker-sw.js');
+ * ```
+ *
+ * @example Module SW (`type: 'module'`)
+ * ```js
+ * import { installChaosSW } from '@chaos-maker/core/sw';
+ * installChaosSW();
+ * ```
+ */
+export declare function installChaosSW(opts?: InstallChaosSWOptions): SWChaosHandle;
+export type { ChaosConfig, ChaosEvent };

package/dist/types/transport.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Transport-safe (de)serialization for `ChaosConfig` values that may carry
+ * `RegExp` instances.
+ *
+ * Why: every adapter passes config across the Node ↔ browser boundary via a
+ * channel that JSON-encodes its argument (Playwright `addInitScript`,
+ * Puppeteer `evaluateOnNewDocument`, WDIO `JSON.stringify(...)` into a script
+ * tag). `JSON.stringify` collapses `RegExp` to `{}`, which silently breaks
+ * matchers like `graphqlOperation: /^Get/`.
+ *
+ * `serializeForTransport` walks the config and replaces every `RegExp` with a
+ * plain marker object that survives JSON. `deserializeForTransport` reverses
+ * the substitution. Both are pure and structurally recursive — they don't
+ * touch other values.
+ */
+/** Replace every `RegExp` instance in `value` with a JSON-safe marker object.
+ *  Pass through everything else (primitives, arrays, plain objects). */
+export declare function serializeForTransport<T>(value: T): T;
+/** Reconstruct any `RegExp` markers in `value` produced by `serializeForTransport`.
+ *  Idempotent: passing a fully-deserialized value through a second time is a no-op. */
+export declare function deserializeForTransport<T>(value: T): T;

package/dist/types/utils.d.ts

@@ -1,4 +1,11 @@
-import type { CorruptionStrategy, RequestCountingOptions } from './config';
+import type { ChaosConfig, CorruptionStrategy, RequestCountingOptions } from './config';
+import { RuleGroupRegistry } from './groups';
+import type { ChaosEvent, ChaosEventEmitter } from './events';
+/** Recursive deep clone that preserves `RegExp` instances literally.
+ *  `JSON.parse(JSON.stringify(...))` would silently drop `RegExp`, breaking
+ *  matchers like `graphqlOperation: /^Get/`. Shared by builder + presets so a
+ *  single implementation owns RegExp survival. */
+export declare function cloneValue<T>(value: T): T;
 export declare function shouldApplyChaos(probability: number, random: () => number): boolean;
 /**
  * Increment the per-rule request counter and return the new count.
@@ -14,3 +21,41 @@ export declare function incrementCounter(rule: object, counters: Map<object, num
 export declare function checkCountingCondition(rule: RequestCountingOptions, count: number): boolean;
 export declare function matchUrl(url: string, pattern: string): boolean;
 export declare function corruptText(text: string, strategy: CorruptionStrategy): string;
+/**
+ * Group-active gate. Sits between `gateRule` and `shouldApplyChaos`
+ * inside every interceptor.
+ *
+ * - `registry === undefined` (legacy / direct interceptor caller): returns
+ *   `true` so the interceptor proceeds without group checks.
+ * - When the rule's group is enabled: returns `true`.
+ * - When disabled: emits at most one `rule-group:gated` event per group per
+ *   toggle cycle (deduped via `RuleGroupRegistry.shouldEmitGated`) and
+ *   returns `false`. The emitted detail merges `baseDetail` (e.g. url +
+ *   method) with `groupName`.
+ *
+ * Counting (`onNth` / `everyNth` / `afterN`) runs *before* this gate inside
+ * `gateRule`, so toggling a group does not desync per-rule counters.
+ */
+export declare function gateGroup(rule: {
+    group?: string;
+}, registry: RuleGroupRegistry | undefined, emitter: ChaosEventEmitter | undefined, baseDetail: ChaosEvent['detail']): boolean;
+/** Minimal rule shape walked by `forEachRule`. Carries the optional `group`
+ *  field every rule type now supports plus an open index for the
+ *  remaining per-rule fields the walker doesn't care about. */
+export type AnyRule = {
+    group?: string;
+    [k: string]: unknown;
+};
+/**
+ * Iterate every rule across every chaos category in the config exactly once.
+ *
+ * IMPORTANT: any new rule array added to `ChaosConfig` (e.g. `websocket.timeouts`,
+ * `sse.reconnects`) MUST be registered here. The matching test in
+ * `forEachRule.test.ts` asserts the visited count against a sample config; that
+ * test will fail loudly if a new array is added without updating this walker.
+ *
+ * Single source of truth for rule iteration. Used by `seedGroupsFromRules`
+ * and `collectReferencedGroups` in `ChaosMaker`, plus any future feature
+ * that needs to walk all rules.
+ */
+export declare function forEachRule(config: ChaosConfig, fn: (rule: AnyRule) => void): void;

package/dist/types/validation-deprecation.d.ts

@@ -0,0 +1,7 @@
+import type { ChaosConfig } from './config';
+import type { DeprecationEntry, ValidationIssue } from './validation-types';
+/** Empty for v0.5.0 — rails only. First real deprecation lands in v0.5.x by
+ *  adding an entry here keyed by a dot-notation path the walker can detect.
+ *  Top-level paths only for now (e.g. `'someTopLevelField'`). */
+export declare const DEPRECATED_FIELDS: Map<string, DeprecationEntry>;
+export declare function checkDeprecations(config: ChaosConfig, onDeprecation?: (issue: ValidationIssue) => void): void;

package/dist/types/validation-format.d.ts

@@ -0,0 +1,10 @@
+import type { ZodIssue } from 'zod';
+import type { ValidationIssue } from './validation-types';
+export declare function formatZodIssue(issue: ZodIssue): ValidationIssue;
+export interface RenderOptions {
+    maxIssues?: number;
+}
+/** Deterministic sort: lex on path, then lex on code. Pure (returns a new
+ *  array). Modern `Array#sort` is stable so equal pairs preserve input order. */
+export declare function sortIssues(issues: ValidationIssue[]): ValidationIssue[];
+export declare function renderValidationIssues(issues: ValidationIssue[], opts?: RenderOptions): string;

package/dist/types/validation-strip.d.ts

@@ -0,0 +1,11 @@
+/** Known-key projection for `unknownFields: 'warn' | 'ignore'`. The walker is
+ *  a small recursive helper, NOT a third Zod schema. Returns a fresh object
+ *  detached from the passthrough parse result so subsequent stages cannot leak
+ *  unknown fields back through aliasing. */
+import type { ChaosConfig } from './config';
+/** Project `input` to a fresh object containing only the keys recognized by
+ *  the strict schema. Never mutates the input. */
+export declare function stripUnknownKeys(input: unknown): ChaosConfig;
+/** Collect dot-notation paths of unknown keys. Deterministic sorted output.
+ *  Does not mutate the input. */
+export declare function collectUnknownPaths(input: unknown): string[];

package/dist/types/validation-types.d.ts

@@ -0,0 +1,34 @@
+/** Public types for the structured validation surface.
+ *  Pure types — no runtime. Imported by `errors.ts`, `validation.ts`, and the
+ *  format / strip / deprecation helpers. */
+export type RuleType = 'network.failure' | 'network.latency' | 'network.abort' | 'network.corruption' | 'network.cors' | 'ui.assault' | 'websocket.drop' | 'websocket.delay' | 'websocket.corrupt' | 'websocket.close' | 'sse.drop' | 'sse.delay' | 'sse.corrupt' | 'sse.close' | 'group' | 'preset' | 'top-level';
+export type ValidationIssueCode = 'unknown_field' | 'missing_field' | 'invalid_type' | 'value_too_small' | 'value_too_large' | 'invalid_enum' | 'invalid_string' | 'invalid_regex' | 'mutually_exclusive' | 'duplicate' | 'unknown_preset' | 'preset_chain' | 'preset_collision' | 'unknown_schema_version' | 'deprecated' | 'custom' | 'legacy';
+export interface ValidationIssue {
+    /** Dot-notation path: 'network.failures[0].statusCode'. Empty string for top-level. */
+    path: string;
+    code: ValidationIssueCode;
+    ruleType: RuleType;
+    message: string;
+    /** JSON-stringifiable. e.g. 'number 0..1', "'truncate'|'malformed-json'|...". */
+    expected?: string;
+    /** Received value via JSON.stringify (clipped to 80 chars). */
+    received?: string;
+}
+/** Custom validator hook. Rule passed by reference as `unknown`; callers
+ *  narrow via type guards. Concrete `Readonly<NetworkFailureConfig>`-style
+ *  typings per rule type are deferred post-v0.5.0.
+ *
+ *  Mutation of the rule arg is undefined behavior. The engine deep-clones
+ *  the canonical config at expansion time, so mutations made here may be
+ *  observable on the validator's input but not by the running engine. */
+export type CustomRuleValidator = (rule: unknown, ctx: Readonly<{
+    ruleType: RuleType;
+    path: string;
+}>) => ValidationIssue[] | void;
+export type CustomValidatorMap = Readonly<Partial<Record<RuleType, CustomRuleValidator>>>;
+export interface DeprecationEntry {
+    since: string;
+    replacement?: string;
+    removeIn?: string;
+    message: string;
+}

package/dist/types/validation.d.ts

@@ -1,2 +1,54 @@
+import { z } from 'zod';
 import type { ChaosConfig } from './config';
+import type { CustomValidatorMap, ValidationIssue } from './validation-types';
+/** Prebuilt strict variant. Default for `unknownFields: 'reject'` and for the
+ *  post-preset-expansion second pass. Built once at module load. Typed as
+ *  `z.ZodTypeAny` to keep DTS output tractable; runtime keeps the full
+ *  schema graph. */
+export declare const chaosConfigSchemaStrict: z.ZodTypeAny;
+/** Prebuilt passthrough variant. Used for `unknownFields: 'warn' | 'ignore'`
+ *  before `stripUnknownKeys` projects the result to known keys only. */
+export declare const chaosConfigSchemaPassthrough: z.ZodTypeAny;
+/** Bumped whenever the validator's invariants change semantically. Stale
+ *  brands fail the strict-equality check inside the short-circuit and re-
+ *  validate. Do NOT bump for cosmetic / refactor-only changes. */
+export declare const VALIDATOR_BRAND_VERSION = 1;
+/** Schema-only validation. Does NOT expand presets and does NOT run the
+ *  post-merge re-validation pass. Calling this in a runtime path silently
+ *  bypasses preset expansion. For runtime preparation, call
+ *  `prepareChaosConfig` (or `validateChaosConfig` for the full structured
+ *  pipeline). */
 export declare function validateConfig(config: unknown): ChaosConfig;
+export interface PrepareChaosConfigOptions {
+    unknownFields?: 'reject' | 'warn' | 'ignore';
+}
+/** Canonical runtime preparation entry point for a `ChaosConfig`.
+ *
+ *  Composes:
+ *    1. Zod pass 1 (strict OR passthrough+strip per `opts.unknownFields`).
+ *    2. Build per-instance `PresetRegistry`, register customs.
+ *    3. `expandPresets` — append rule arrays + groups, strip preset fields.
+ *    4. Zod pass 2 (strict, on the merged config).
+ *
+ *  v0.4.x callers pass no opts and get strict-by-default behavior identical
+ *  to before. */
+export declare function prepareChaosConfig(input: unknown, opts?: PrepareChaosConfigOptions): ChaosConfig;
+export interface ValidateChaosConfigOptions {
+    unknownFields?: 'reject' | 'warn' | 'ignore';
+    onDeprecation?: (issue: ValidationIssue) => void;
+    customValidators?: CustomValidatorMap;
+}
+/** Canonical validation entry point for adapters and the engine.
+ *
+ *  Pipeline:
+ *    1. Schema-version gate (BEFORE Zod, unambiguous message).
+ *    2. Brand short-circuit (only when brand-version matches AND opts empty).
+ *    3-5. `prepareChaosConfig` — Zod pass 1 + preset expansion + Zod pass 2.
+ *    6. Deprecation walk.
+ *    7. Custom validators.
+ *    8. Issue sort (inside ChaosConfigError construction).
+ *    9. Brand stamp — final step only.
+ *
+ *  Throws `ChaosConfigError` aggregating all issues from the first failing
+ *  layer. Subsequent layers are skipped on failure. */
+export declare function validateChaosConfig(input: unknown, opts?: ValidateChaosConfigOptions): ChaosConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaos-maker/core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "A lightweight, framework-agnostic toolkit for injecting chaos into web applications to test frontend resilience",
   "keywords": [
@@ -17,12 +17,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jvjithin/chaos-maker.git",
+    "url": "https://github.com/chaos-maker-dev/chaos-maker.git",
     "directory": "packages/core"
   },
-  "homepage": "https://github.com/jvjithin/chaos-maker",
+  "homepage": "https://github.com/chaos-maker-dev/chaos-maker",
   "bugs": {
-    "url": "https://github.com/jvjithin/chaos-maker/issues"
+    "url": "https://github.com/chaos-maker-dev/chaos-maker/issues"
   },
   "engines": {
     "node": ">=18"
@@ -40,6 +40,11 @@
         "types": "./dist/types/index.d.ts",
         "default": "./dist/chaos-maker.cjs"
       }
+    },
+    "./sw": {
+      "types": "./dist/types/sw.d.ts",
+      "import": "./dist/sw.mjs",
+      "default": "./dist/sw.js"
     }
   },
   "files": [
@@ -53,11 +58,13 @@
     "jsdom": "^27.0.1",
     "typescript": "^5.4.5",
     "vite": "^6.4.2",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "zod-to-json-schema": "3.24.5"
   },
   "scripts": {
     "dev": "vite build --watch",
-    "build": "vite build && tsc -p tsconfig.build.json",
+    "build": "vite build && vite build -c vite.config.sw.ts && tsc -p tsconfig.build.json && pnpm run build:schema",
+    "build:schema": "node scripts/build-schema.mjs",
     "test": "vitest run",
     "test:watch": "vitest"
   }