@chaos-maker/core 0.4.0 → 0.6.0

package/dist/types/ChaosMaker.d.ts

@@ -1,5 +1,7 @@
 import { ChaosConfig } from './config';
+import { type ValidateChaosConfigOptions } from './validation';
 import { ChaosEvent, ChaosEventType, ChaosEventListener } from './events';
+import { RuleGroup } from './groups';
 /**
  * Global context ChaosMaker patches against. Must expose at minimum `fetch`
  * (network chaos), and optionally `XMLHttpRequest` / `WebSocket`. In a
@@ -14,6 +16,12 @@ export interface ChaosMakerOptions {
      * `window` or `self` explicitly only for cross-context testing.
      */
     target?: ChaosTarget;
+    /**
+     * Forwarded to `validateChaosConfig` during construction. Use to
+     * relax unknown-field handling, hook deprecation events, or run custom
+     * per-`RuleType` validators.
+     */
+    validation?: ValidateChaosConfigOptions;
 }
 export declare class ChaosMaker {
     private config;
@@ -32,13 +40,51 @@ export declare class ChaosMaker {
     private eventSourceHandle?;
     /** Shared counters keyed by config rule object reference. Shared across fetch + XHR + WS. */
     private requestCounters;
+    /** Rule-group registry. Default-on; default group always exists. */
+    private groups;
+    /** Positional rule-id map shared across interceptors via emitter.
+     *  Built lazily — only when debug mode is enabled — so disabled instances
+     *  pay zero allocation cost. The emitter handles `undefined` ruleIds
+     *  internally via `?.get(rule)`. */
+    private ruleIds?;
+    /** Logger fed into the emitter; absent ⇒ debug fast-path no-op. */
+    private logger?;
     constructor(config: ChaosConfig, options?: ChaosMakerOptions);
+    private seedGroupsFromRules;
+    private emitInvariant;
+    private emitStartInvariantDiagnostics;
+    private emitStopInvariantDiagnostics;
+    private emitPatchDiagnostic;
+    private runCleanupStep;
+    /** Compute the set of group names currently referenced by any rule. Used by `removeGroup`. */
+    private collectReferencedGroups;
     /** Get the seed used by this instance. Log this on failure to reproduce exact chaos decisions. */
     getSeed(): number;
     on(type: ChaosEventType | '*', listener: ChaosEventListener): void;
     off(type: ChaosEventType | '*', listener: ChaosEventListener): void;
     getLog(): ChaosEvent[];
     clearLog(): void;
+    /** Enable a rule group at runtime. Auto-creates the group if unknown.
+     *  Engine state and per-rule counters are preserved — no restart. */
+    enableGroup(name: string): void;
+    /** Disable a rule group at runtime. Subsequent matches are skipped
+     *  and a single `rule-group:gated` event is emitted per cycle. */
+    disableGroup(name: string): void;
+    /** Pre-register a group (typically used to ship one as initially disabled). */
+    createGroup(name: string, opts?: {
+        enabled?: boolean;
+    }): void;
+    /** Remove a group from the registry. Throws when still referenced unless
+     *  `{ force: true }`. `'default'` cannot be removed. */
+    removeGroup(name: string, opts?: {
+        force?: boolean;
+    }): boolean;
+    hasGroup(name: string): boolean;
+    /** True iff the named group is currently enabled (auto-creates unknown names). */
+    getGroupState(name: string): boolean;
+    /** Snapshot of every known group as `{ name: enabled }`. */
+    getGroupsSnapshot(): Record<string, boolean>;
+    listGroups(): RuleGroup[];
     start(): void;
     stop(): void;
 }

package/dist/types/builder.d.ts

@@ -1,7 +1,25 @@
 import { ChaosConfig, CorruptionStrategy, GraphQLOperationMatcher, RequestCountingOptions, SSECorruptionStrategy, WebSocketDirection, WebSocketCorruptionStrategy } from './config';
 export declare class ChaosConfigBuilder {
     private config;
+    /** Single-shot group name applied to the next rule pushed and then cleared.
+     *  Sticky semantics intentionally rejected — silent capture of stale groups
+     *  is harder to debug than the explicit re-chain. */
+    private pendingGroup?;
+    /** Queued preset names for `.usePreset(...)`. Silently deduped on
+     *  push. Flushed onto `out.presets` in `.build()` when non-empty. */
+    private pendingPresets;
     constructor(initialConfig?: ChaosConfig);
+    /** Tag the next rule pushed with this group name.
+     *  Single-shot: cleared after the next builder method that pushes a rule. */
+    inGroup(name: string): this;
+    /** Pre-register a group on the config (typically used to ship one as
+     *  initially disabled). Equivalent to setting `ChaosConfig.groups` directly. */
+    defineGroup(name: string, opts?: {
+        enabled?: boolean;
+    }): this;
+    /** Apply `pendingGroup` (single-shot) to a rule literal before it is pushed.
+     *  MUST be called at every rule-push site so `.inGroup(...)` is honored. */
+    private withGroup;
     failRequests(urlPattern: string, statusCode: number, probability: number, methods?: string[], body?: string, headers?: Record<string, string>, counting?: RequestCountingOptions): this;
     addLatency(urlPattern: string, delayMs: number, probability: number, methods?: string[], counting?: RequestCountingOptions): this;
     abortRequests(urlPattern: string, probability: number, timeout?: number, methods?: string[], counting?: RequestCountingOptions): this;
@@ -47,5 +65,11 @@ export declare class ChaosConfigBuilder {
     }, counting?: RequestCountingOptions): this;
     /** Set the PRNG seed for reproducible chaos. */
     withSeed(seed: number): this;
+    /** Toggle Debug Mode on this config. Off by default. */
+    withDebug(enabled?: boolean): this;
+    /** Queue a preset name to be expanded at engine init.
+     *  Silently dedups within the builder, preserving insertion order. Empty
+     *  / whitespace-only names throw, matching the schema and registry rules. */
+    usePreset(name: string): this;
     build(): ChaosConfig;
 }

package/dist/types/config.d.ts

@@ -1,3 +1,5 @@
+import type { RuleGroupConfig } from './groups';
+import type { PresetConfigSlice } from './presets';
 /** Counting options shared by all network chaos config types.
  *  At most one of `onNth`, `everyNth`, or `afterN` may be set on a single rule.
  *  Counting is per-rule and shared across fetch + XHR (only increments when a
@@ -11,6 +13,14 @@ export interface RequestCountingOptions {
     everyNth?: number;
     afterN?: number;
 }
+/** Optional group membership shared by every rule type.
+ *  Rules without a `group` belong to the implicit `'default'` group, which is
+ *  always enabled. Toggling a group at runtime via `enableGroup` /
+ *  `disableGroup` skips its rules without restarting the engine — counters
+ *  stay intact across toggles. */
+export interface RuleGroupAssignment {
+    group?: string;
+}
 /** Match a GraphQL operation by name. Applied AFTER `urlPattern` + `methods`
  *  as an additive filter — never a replacement. Matches against:
  *  - JSON `operationName` field on POST request bodies, OR
@@ -33,27 +43,27 @@ export interface NetworkRuleMatchers {
     methods?: string[];
     graphqlOperation?: GraphQLOperationMatcher;
 }
-export interface NetworkFailureConfig extends RequestCountingOptions, NetworkRuleMatchers {
+export interface NetworkFailureConfig extends RequestCountingOptions, NetworkRuleMatchers, RuleGroupAssignment {
     statusCode: number;
     probability: number;
     body?: string;
     statusText?: string;
     headers?: Record<string, string>;
 }
-export interface NetworkLatencyConfig extends RequestCountingOptions, NetworkRuleMatchers {
+export interface NetworkLatencyConfig extends RequestCountingOptions, NetworkRuleMatchers, RuleGroupAssignment {
     delayMs: number;
     probability: number;
 }
-export interface NetworkAbortConfig extends RequestCountingOptions, NetworkRuleMatchers {
+export interface NetworkAbortConfig extends RequestCountingOptions, NetworkRuleMatchers, RuleGroupAssignment {
     probability: number;
     timeout?: number;
 }
 export type CorruptionStrategy = 'truncate' | 'malformed-json' | 'empty' | 'wrong-type';
-export interface NetworkCorruptionConfig extends RequestCountingOptions, NetworkRuleMatchers {
+export interface NetworkCorruptionConfig extends RequestCountingOptions, NetworkRuleMatchers, RuleGroupAssignment {
     probability: number;
     strategy: CorruptionStrategy;
 }
-export interface NetworkCorsConfig extends RequestCountingOptions, NetworkRuleMatchers {
+export interface NetworkCorsConfig extends RequestCountingOptions, NetworkRuleMatchers, RuleGroupAssignment {
     probability: number;
 }
 export interface NetworkConfig {
@@ -63,7 +73,7 @@ export interface NetworkConfig {
     corruptions?: NetworkCorruptionConfig[];
     cors?: NetworkCorsConfig[];
 }
-export interface UiAssaultConfig {
+export interface UiAssaultConfig extends RuleGroupAssignment {
     selector: string;
     action: 'disable' | 'hide' | 'remove';
     probability: number;
@@ -77,12 +87,12 @@ export interface UiConfig {
  *  - `both`     = apply independently in either direction.
  */
 export type WebSocketDirection = 'inbound' | 'outbound' | 'both';
-export interface WebSocketDropConfig extends RequestCountingOptions {
+export interface WebSocketDropConfig extends RequestCountingOptions, RuleGroupAssignment {
     urlPattern: string;
     direction: WebSocketDirection;
     probability: number;
 }
-export interface WebSocketDelayConfig extends RequestCountingOptions {
+export interface WebSocketDelayConfig extends RequestCountingOptions, RuleGroupAssignment {
     urlPattern: string;
     direction: WebSocketDirection;
     delayMs: number;
@@ -95,13 +105,13 @@ export interface WebSocketDelayConfig extends RequestCountingOptions {
  *  emitted with `applied: false`.
  */
 export type WebSocketCorruptionStrategy = 'truncate' | 'malformed-json' | 'empty' | 'wrong-type';
-export interface WebSocketCorruptConfig extends RequestCountingOptions {
+export interface WebSocketCorruptConfig extends RequestCountingOptions, RuleGroupAssignment {
     urlPattern: string;
     direction: WebSocketDirection;
     strategy: WebSocketCorruptionStrategy;
     probability: number;
 }
-export interface WebSocketCloseConfig extends RequestCountingOptions {
+export interface WebSocketCloseConfig extends RequestCountingOptions, RuleGroupAssignment {
     urlPattern: string;
     /**
      * WebSocket close code. Must be either `1000` (Normal Closure) or in the
@@ -138,24 +148,24 @@ export type SSECorruptionStrategy = 'truncate' | 'malformed-json' | 'empty' | 'w
  *  - `'*'` matches every event regardless of name.
  */
 export type SSEEventTypeMatcher = string | '*';
-export interface SSEDropConfig extends RequestCountingOptions {
+export interface SSEDropConfig extends RequestCountingOptions, RuleGroupAssignment {
     urlPattern: string;
     eventType?: SSEEventTypeMatcher;
     probability: number;
 }
-export interface SSEDelayConfig extends RequestCountingOptions {
+export interface SSEDelayConfig extends RequestCountingOptions, RuleGroupAssignment {
     urlPattern: string;
     eventType?: SSEEventTypeMatcher;
     delayMs: number;
     probability: number;
 }
-export interface SSECorruptConfig extends RequestCountingOptions {
+export interface SSECorruptConfig extends RequestCountingOptions, RuleGroupAssignment {
     urlPattern: string;
     eventType?: SSEEventTypeMatcher;
     strategy: SSECorruptionStrategy;
     probability: number;
 }
-export interface SSECloseConfig extends RequestCountingOptions {
+export interface SSECloseConfig extends RequestCountingOptions, RuleGroupAssignment {
     urlPattern: string;
     /** Delay after `open` before dispatching `error` + closing, in ms. Default 0. */
     afterMs?: number;
@@ -172,6 +182,64 @@ export interface ChaosConfig {
     ui?: UiConfig;
     websocket?: WebSocketConfig;
     sse?: SSEConfig;
+    /**
+     * Pre-register rule groups with an explicit initial enabled state.
+     *
+     * Rules opt into a group by setting `group: 'name'`; groups referenced from
+     * rules but not listed here are auto-registered as enabled. Use this field
+     * only to ship a group as initially disabled (e.g. `{ name: 'payments',
+     * enabled: false }`) or to reserve a group name with no rules attached yet.
+     */
+    groups?: RuleGroupConfig[];
+    /**
+     * Enable Chaos Maker's structured Debug Mode. When `true`, every
+     * rule decision emits a `type: 'debug'` event (with `detail.stage`)
+     * through the emitter AND mirrors a `[Chaos] <stage> ...` line to
+     * `console.debug`. Framework-agnostic — does not touch
+     * Playwright/Cypress/Puppeteer/WDIO debug semantics. Defaults to `false`;
+     * fast-path no-op when off.
+     *
+     * Accepts `boolean` for the common case or `{ enabled: boolean }` to match
+     * the `DebugOptions` shape that future Debug Mode extensions (`level`,
+     * `prefix`, `console`, `sink`) will add. The validator coerces both forms;
+     * the runtime normalizes them via `normalizeDebugOption()`.
+     */
+    debug?: boolean | {
+        enabled: boolean;
+    };
+    /**
+     * Names of presets to expand into this config at engine init.
+     * Resolved against the per-instance `PresetRegistry` seeded with built-ins
+     * (camelCase names plus the four kebab-case aliases) and any
+     * `customPresets` provided alongside this field.
+     *
+     * Merge semantics: append-only. Each preset's rule arrays concatenate onto
+     * the user's rule arrays in the order listed here, preset rules first and
+     * user rules last. Duplicate names are silently deduplicated, preserving
+     * first occurrence. Unknown names throw `ChaosConfigError` at construction.
+     *
+     * Preset configs themselves cannot carry `presets` or `customPresets` —
+     * dependency chains are out of scope and rejected by the schema.
+     */
+    presets?: string[];
+    /**
+     * Per-instance custom presets registered alongside the built-ins.
+     * Each value is a `PresetConfigSlice` (a `ChaosConfig` minus `presets`,
+     * `customPresets`, `seed`, and `debug`). Names collide fail-fast against
+     * built-ins and against each other — pick a unique label.
+     *
+     * Custom preset literals stay mutable on input; the engine deep-clones them
+     * during expansion, so post-construction tweaks are not observed by the
+     * runtime.
+     */
+    customPresets?: Record<string, PresetConfigSlice>;
+    /**
+     * Reserved for forward-compatibility with future shape changes.
+     * Defaults to `1`. Unknown values are rejected at validation time with
+     * `code: 'unknown_schema_version'`. Omit this field unless a future major
+     * release explicitly bumps the supported version.
+     */
+    schemaVersion?: 1;
     /**
      * Seed for Chaos Maker's PRNG.
      *

package/dist/types/debug.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Debug Mode.
+ *
+ * Two-sink logger that fires when `ChaosConfig.debug` is `true`:
+ *   1. Structured `type: 'debug'` events through `ChaosEventEmitter` —
+ *      consumers subscribe via `instance.on('debug', cb)` and switch on
+ *      `event.detail.stage` for the stage taxonomy.
+ *   2. A formatted `[Chaos] <stage> ...` line (or `[Chaos SW] <stage> ...`
+ *      when the logger targets a Service Worker) to `console.debug`. Hidden
+ *      by default in CI loggers, visible in browser DevTools.
+ *
+ * Framework-agnostic: never reads `process.env.DEBUG`, `--debug`, or
+ * `localStorage.debug`. The only signal is `ChaosConfig.debug`.
+ */
+import type { ChaosConfig } from './config';
+import type { ChaosDebugStage, ChaosEvent } from './events';
+export type { ChaosDebugStage } from './events';
+export interface DebugOptions {
+    enabled: boolean;
+}
+export declare function normalizeDebugOption(input: boolean | DebugOptions | undefined): DebugOptions;
+/** Identity assigned to every rule object in a config snapshot. */
+export interface RuleIdEntry {
+    ruleType: string;
+    ruleId: string;
+}
+/**
+ * Build a positional rule-id map for a config snapshot. IDs are
+ * `<ruleType>#<index>` derived from the order rules appear in their array.
+ * Reordering rules between runs changes the IDs — acceptable for in-test
+ * diagnostics.
+ */
+export declare function buildRuleIdMap(config: ChaosConfig): WeakMap<object, RuleIdEntry>;
+/**
+ * Build the human-readable body mirrored to `console.debug`. Does NOT include
+ * the `[Chaos]` / `[Chaos SW]` prefix — that is owned by `Logger.log()` and
+ * varies by target so the two never compose into a doubled prefix.
+ */
+export declare function formatDebugMessage(stage: ChaosDebugStage, detail: ChaosEvent['detail']): string;
+export declare class Logger {
+    private readonly opts;
+    private readonly target;
+    constructor(opts: DebugOptions, target?: 'page' | 'sw');
+    isEnabled(): boolean;
+    /**
+     * Build a `type: 'debug'` event with `detail.stage = stage`, mirror a
+     * `[Chaos] ...` (page) or `[Chaos SW] ...` (Service Worker) line to
+     * `console.debug`, and return the event for the emitter to fan out. The
+     * formatted string is never stored on the event payload.
+     *
+     * Returns `null` when the logger was constructed with `enabled: false`.
+     * Internal callers (the emitter fast-path) never reach this branch because
+     * `ChaosMaker` does not attach a logger when debug is off, but the guard
+     * keeps the public `Logger` API consistent with the `DebugOptions.enabled`
+     * contract for external consumers who instantiate it directly.
+     */
+    log(stage: ChaosDebugStage, detail: ChaosEvent['detail']): ChaosEvent | null;
+}

package/dist/types/errors.d.ts

@@ -1,4 +1,16 @@
+import type { ValidationIssue } from './validation-types';
+/** Aggregate validation failure thrown by `validateChaosConfig` /
+ *  `prepareChaosConfig` / `validateConfig`.
+ *
+ *  Issues are deterministically sorted (by `path` then `code`) before render
+ *  so CI logs and snapshot tests stay stable across runs. The render is
+ *  capped at 50 entries with a `... and N more` summary; the full list is
+ *  always retained on `.issues` for programmatic inspection. */
 export declare class ChaosConfigError extends Error {
-    readonly issues: string[];
-    constructor(issues: string[]);
+    readonly issues: ValidationIssue[];
+    constructor(input: ValidationIssue[] | string[]);
+    /** v0.4.x-shaped string array. Concatenates `path` + `message` per issue
+     *  in the same sorted order as `.issues`. Use for log greps that already
+     *  consume the legacy shape; new code should read `.issues` directly. */
+    get messages(): string[];
 }

package/dist/types/events.d.ts

@@ -1,4 +1,25 @@
-export type ChaosEventType = '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';
+import type { Logger, RuleIdEntry } from './debug';
+export type ChaosEventType = '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'
+/** Emitted once per `enableGroup()` call. `applied: true`. */
+ | 'rule-group:enabled'
+/** Emitted once per `disableGroup()` call. `applied: true`. */
+ | 'rule-group:disabled'
+/** Emitted once per group per toggle cycle when a rule is skipped because
+ *  its group is disabled. Deduped — at most one event per group between
+ *  toggles to avoid log floods. `applied: false`. */
+ | 'rule-group:gated'
+/** Single Debug Mode event type. The concrete stage of the rule
+ *  decision pipeline lives on `detail.stage`. `applied: false`. */
+ | 'debug';
+/** Stage taxonomy. Stable strings used as `detail.stage` on every
+ *  `type: 'debug'` event. Defined here (not in `debug.ts`) so the event-detail
+ *  union can reference it without a circular runtime import. */
+export type ChaosDebugStage = 'rule-evaluating' | 'rule-matched' | 'rule-skip-match' | 'rule-skip-counting' | 'rule-skip-group' | 'rule-skip-probability' | 'rule-applied' | 'lifecycle';
+/** Lifecycle phases. Set on `detail.phase` only when
+ *  `detail.stage === 'lifecycle'`. WS/SSE direction continues to live on
+ *  the existing `detail.direction` field — `phase` is intentionally
+ *  lifecycle-only to avoid overloading. */
+export type ChaosLifecyclePhase = 'engine:start' | 'engine:stop' | 'engine:group-toggled' | 'sw:install' | 'sw:config-applied' | 'sw:config-stopped' | 'sw:group-toggled';
 export interface ChaosEvent {
     type: ChaosEventType;
     timestamp: number;
@@ -28,6 +49,29 @@ export interface ChaosEvent {
         operationName?: string;
         /** Reason string for diagnostic `applied: false` events. */
         reason?: string;
+        /** Group name (for `rule-group:*` events, and on gated rule diagnostics). */
+        groupName?: string;
+        /** New state of a group when `stage === 'lifecycle'` and
+         *  `phase === 'engine:group-toggled' | 'sw:group-toggled'`. Distinguishes
+         *  enable from disable on the debug stream so consumers don't have to
+         *  pivot on the parallel `rule-group:enabled` / `rule-group:disabled`
+         *  emitter events. */
+        enabled?: boolean;
+        /** Concrete stage of a rule's decision pipeline. Set on every
+         *  `type: 'debug'` event; unset on non-debug events. */
+        stage?: ChaosDebugStage;
+        /** Lifecycle phase, set only when `stage === 'lifecycle'`. */
+        phase?: ChaosLifecyclePhase;
+        /** Rule category — `'failure' | 'latency' | 'abort' | ...`. */
+        ruleType?: string;
+        /** Deterministic identifier for a specific rule WITHIN A SINGLE
+         *  CONFIG SNAPSHOT. Positional: reordering rules in your config changes
+         *  the IDs. Sufficient for in-test diagnostic pinpointing in v0.5.0. */
+        ruleId?: string;
+        /** Optional human label for a rule (future builder field).
+         *  Reserved so the event shape doesn't churn when the builder later
+         *  gains `.failRequests({..., name: 'slow-api'})`. */
+        ruleName?: string;
     };
 }
 export type ChaosEventListener = (event: ChaosEvent) => void;
@@ -35,10 +79,24 @@ export declare class ChaosEventEmitter {
     private readonly maxLogEntries;
     private listeners;
     private log;
+    private logger;
+    private ruleIds;
     constructor(maxLogEntries?: number);
     on(type: ChaosEventType | '*', listener: ChaosEventListener): void;
     off(type: ChaosEventType | '*', listener: ChaosEventListener): void;
     emit(event: ChaosEvent): void;
+    /** Attach a Debug Mode logger. When unset, `debug()` is a fast-path no-op. */
+    setLogger(logger: Logger | undefined): void;
+    /** Attach the rule-id map so debug events auto-resolve `ruleType` /
+     *  `ruleId` from a rule object reference. */
+    setRuleIds(map: WeakMap<object, RuleIdEntry> | undefined): void;
+    /**
+     * Emit a Debug Mode event. Fast-path no-op when no logger is attached —
+     * single undefined-check before any allocation. When `rule` is supplied
+     * and present in the rule-id map, `detail.ruleType` and `detail.ruleId`
+     * are filled in automatically.
+     */
+    debug(stage: ChaosDebugStage, detail: ChaosEvent['detail'], rule?: object): void;
     getLog(): ChaosEvent[];
     clearLog(): void;
     private notify;

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

@@ -0,0 +1,13 @@
+import type { ChaosEvent } from './events';
+/**
+ * Format a chaos event into a compact, human-readable trace step title.
+ * Keeps titles under about 80 chars; truncates long URLs from the left to
+ * preserve the distinguishing path/query tail.
+ */
+export declare function formatStepTitle(event: ChaosEvent): string;
+/**
+ * Decide whether an event should emit a live runner step or command-log entry.
+ * Skipped events only render live when verbose output is enabled. Debug events
+ * stay JSON-only because they are high-volume by design.
+ */
+export declare function shouldEmitStep(event: ChaosEvent, verbose: boolean): boolean;

package/dist/types/groups.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Rule Groups — bulk runtime enable/disable for chaos rules.
+ *
+ * A `RuleGroupRegistry` tracks named groups (default-on) and answers
+ * `isActive(name)` from interceptors before they apply chaos. Groups not
+ * declared up-front are auto-registered the first time they are referenced
+ * (typo surfacing — appears in `list()` / `getSnapshot()`).
+ *
+ * Toggle is runtime-only: there is no engine restart, so `requestCounters`
+ * survive across `setEnabled()` calls.
+ */
+/** Name of the implicit group all rules without an explicit `group` belong to. */
+export declare const DEFAULT_GROUP_NAME = "default";
+/** Public, declarative form accepted on `ChaosConfig.groups`. */
+export interface RuleGroupConfig {
+    name: string;
+    enabled?: boolean;
+}
+/** Snapshot record describing a group inside the registry. */
+export interface RuleGroup {
+    readonly name: string;
+    enabled: boolean;
+    /** True when registered via `ChaosConfig.groups` or `createGroup()`. False when auto-registered from `isActive()`. */
+    explicit: boolean;
+}
+export declare class RuleGroupRegistry {
+    private groups;
+    /**
+     * Tracks groups that have already emitted a `rule-group:gated` event since
+     * the last toggle. Cleared on every `setEnabled()` so the next toggle cycle
+     * gets a fresh diagnostic event without flooding.
+     */
+    private gatedEmitted;
+    /**
+     * Look up an existing group or create a new one.
+     *
+     * - Implicit (auto-create from `isActive`): `explicit: false`, defaults
+     *   `enabled: true`.
+     * - Explicit (`ChaosConfig.groups` / `createGroup()`): `explicit: true`.
+     *   When called with both `explicit: true` and `enabled` set, the existing
+     *   group's `enabled` is overwritten; the explicit form is the source of truth.
+     */
+    ensure(name: string, opts?: {
+        enabled?: boolean;
+        explicit?: boolean;
+    }): RuleGroup;
+    setEnabled(name: string, enabled: boolean): void;
+    /**
+     * Auto-creates unknown groups on first check (implicit). Rationale:
+     * silently returning `true` for unknown names lets typos like
+     * `group: 'paymets'` mask chaos as if no group existed; auto-registering
+     * surfaces the typo via `list()` / `getSnapshot()` and keeps default-on
+     * backward compat.
+     */
+    isActive(name: string | undefined): boolean;
+    /** True when this group should emit a `rule-group:gated` event right now (first block since last toggle). */
+    shouldEmitGated(name: string): boolean;
+    has(name: string): boolean;
+    /**
+     * Remove a group from the registry.
+     * - `'default'` cannot be removed (returns `false`).
+     * - By default, throws when any rule in `referencedBy` still uses the group.
+     * - Pass `{ force: true }` to remove anyway. Subsequent `isActive(name)`
+     *   calls auto-recreate the group (default-on).
+     */
+    remove(name: string, referencedBy: ReadonlySet<string>, opts?: {
+        force?: boolean;
+    }): boolean;
+    list(): RuleGroup[];
+    getSnapshot(): Record<string, boolean>;
+}

package/dist/types/index.d.ts

@@ -1,14 +1,42 @@
 import { ChaosMaker } from './ChaosMaker';
-import { ChaosConfig, CorruptionStrategy, GraphQLOperationMatcher, NetworkFailureConfig, NetworkLatencyConfig, NetworkAbortConfig, NetworkCorruptionConfig, NetworkCorsConfig, NetworkConfig, NetworkRuleMatchers, UiAssaultConfig, UiConfig, WebSocketConfig, WebSocketDropConfig, WebSocketDelayConfig, WebSocketCorruptConfig, WebSocketCloseConfig, WebSocketDirection, WebSocketCorruptionStrategy, SSEConfig, SSEDropConfig, SSEDelayConfig, SSECorruptConfig, SSECloseConfig, SSECorruptionStrategy, SSEEventTypeMatcher } 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 };
+import { formatStepTitle, shouldEmitStep } from './format-event';
+import { formatSeedReproduction } from './seed-reporting';
+/** `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, formatStepTitle, shouldEmitStep, formatSeedReproduction };
+/** 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 { isSessionTeardownError, SESSION_TEARDOWN_PATTERNS } from './session-errors';
 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 { ChaosConfig, CorruptionStrategy, GraphQLOperationMatcher, NetworkFailureConfig, NetworkLatencyConfig, NetworkAbortConfig, NetworkCorruptionConfig, NetworkCorsConfig, NetworkConfig, NetworkRuleMatchers, UiAssaultConfig, UiConfig, WebSocketConfig, WebSocketDropConfig, WebSocketDelayConfig, WebSocketCorruptConfig, WebSocketCloseConfig, WebSocketDirection, WebSocketCorruptionStrategy, SSEConfig, SSEDropConfig, SSEDelayConfig, SSECorruptConfig, SSECloseConfig, SSECorruptionStrategy, SSEEventTypeMatcher, ChaosEvent, ChaosEventType, ChaosEventListener };
+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

@@ -25,6 +25,7 @@
  */
 import { SSEConfig } from '../config';
 import { ChaosEventEmitter } from '../events';
+import type { RuleGroupRegistry } from '../groups';
 export interface EventSourceLikeStatic {
     readonly CONNECTING: 0;
     readonly OPEN: 1;
@@ -38,4 +39,4 @@ export interface EventSourcePatchHandle {
     /** 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>): EventSourcePatchHandle;
+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 globalThis.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

@@ -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 `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;