@chaos-maker/core 0.3.0 → 0.5.0

package/dist/types/ChaosMaker.d.ts

@@ -1,26 +1,85 @@
 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
+ * browser page this is `window`; in a service worker / dedicated worker
+ * this is `self`. `globalThis` resolves to the correct value in both.
+ */
+export type ChaosTarget = typeof globalThis;
+export interface ChaosMakerOptions {
+    /**
+     * Explicit global to install chaos on. Defaults to `globalThis`, which
+     * resolves correctly in both window and service-worker contexts. Pass
+     * `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;
     private emitter;
     private random;
     private seed;
     private running;
+    private target;
     private originalFetch?;
     private originalXhrSend?;
     private originalXhrOpen?;
     private domObserver?;
     private originalWebSocket?;
     private webSocketHandle?;
+    private originalEventSource?;
+    private eventSourceHandle?;
     /** Shared counters keyed by config rule object reference. Shared across fetch + XHR + WS. */
     private requestCounters;
-    constructor(config: ChaosConfig);
+    /** 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;
+    /** 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, RequestCountingOptions, WebSocketDirection, WebSocketCorruptionStrategy } from './config';
+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;
@@ -33,7 +51,25 @@ export declare class ChaosConfigBuilder {
     }, counting?: RequestCountingOptions): this;
     dropMessagesOnNth(urlPattern: string, direction: WebSocketDirection, n: number): this;
     delayMessagesOnNth(urlPattern: string, direction: WebSocketDirection, delayMs: number, n: number): this;
+    /** Fail every GraphQL request matching `operationName`.
+     *  Defaults `urlPattern` to `'*'`; pass an explicit pattern as the 4th
+     *  argument to scope to a specific endpoint. */
+    failGraphQLOperation(operationName: GraphQLOperationMatcher, statusCode: number, probability: number, urlPattern?: string): this;
+    /** Add `delayMs` of latency to every GraphQL request matching `operationName`. */
+    delayGraphQLOperation(operationName: GraphQLOperationMatcher, delayMs: number, probability: number, urlPattern?: string): this;
+    dropSSE(urlPattern: string, probability: number, eventType?: string, counting?: RequestCountingOptions): this;
+    delaySSE(urlPattern: string, delayMs: number, probability: number, eventType?: string, counting?: RequestCountingOptions): this;
+    corruptSSE(urlPattern: string, strategy: SSECorruptionStrategy, probability: number, eventType?: string, counting?: RequestCountingOptions): this;
+    closeSSE(urlPattern: string, probability: number, opts?: {
+        afterMs?: number;
+    }, 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,37 +13,57 @@ export interface RequestCountingOptions {
     everyNth?: number;
     afterN?: number;
 }
-export interface NetworkFailureConfig extends RequestCountingOptions {
+/** 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
+ *  - the operation name parsed from the `query` field (e.g. `query GetUser { … }`),
+ *  - `?operationName=` query parameter for persisted-query GET requests, OR
+ *  - operation name parsed from `?query=` in GET requests carrying GraphQL text.
+ *
+ *  When the rule has `graphqlOperation` set but the request body cannot be
+ *  parsed (multipart upload, ReadableStream, binary), the rule is skipped and
+ *  a diagnostic event is emitted with `applied: false, reason: 'graphql-body-unparseable'`.
+ *  XHR requests with non-string bodies are treated the same way.
+ *
+ *  - `string` matches the operation name exactly.
+ *  - `RegExp` matches when `.test(operationName)` returns true.
+ */
+export type GraphQLOperationMatcher = string | RegExp;
+/** Common matcher fields shared by every network chaos rule type. */
+export interface NetworkRuleMatchers {
     urlPattern: string;
     methods?: string[];
+    graphqlOperation?: GraphQLOperationMatcher;
+}
+export interface NetworkFailureConfig extends RequestCountingOptions, NetworkRuleMatchers, RuleGroupAssignment {
     statusCode: number;
     probability: number;
     body?: string;
     statusText?: string;
     headers?: Record<string, string>;
 }
-export interface NetworkLatencyConfig extends RequestCountingOptions {
-    urlPattern: string;
-    methods?: string[];
+export interface NetworkLatencyConfig extends RequestCountingOptions, NetworkRuleMatchers, RuleGroupAssignment {
     delayMs: number;
     probability: number;
 }
-export interface NetworkAbortConfig extends RequestCountingOptions {
-    urlPattern: string;
-    methods?: string[];
+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 {
-    urlPattern: string;
-    methods?: string[];
+export interface NetworkCorruptionConfig extends RequestCountingOptions, NetworkRuleMatchers, RuleGroupAssignment {
     probability: number;
     strategy: CorruptionStrategy;
 }
-export interface NetworkCorsConfig extends RequestCountingOptions {
-    urlPattern: string;
-    methods?: string[];
+export interface NetworkCorsConfig extends RequestCountingOptions, NetworkRuleMatchers, RuleGroupAssignment {
     probability: number;
 }
 export interface NetworkConfig {
@@ -51,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;
@@ -65,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;
@@ -83,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
@@ -113,10 +135,111 @@ export interface WebSocketConfig {
     corruptions?: WebSocketCorruptConfig[];
     closes?: WebSocketCloseConfig[];
 }
+/** Strategies for corrupting Server-Sent Event payloads.
+ *  All four strategies operate on `event.data` (always a string per the SSE
+ *  spec). Mirrors the fetch / WebSocket corruption shape so the same
+ *  vocabulary applies across protocols.
+ */
+export type SSECorruptionStrategy = 'truncate' | 'malformed-json' | 'empty' | 'wrong-type';
+/** Filter SSE chaos to a specific event type.
+ *  - `'message'` (default in the spec) targets unnamed events fired via
+ *    `onmessage` / `addEventListener('message', …)`.
+ *  - Any other string targets named events dispatched with `event:` lines.
+ *  - `'*'` matches every event regardless of name.
+ */
+export type SSEEventTypeMatcher = string | '*';
+export interface SSEDropConfig extends RequestCountingOptions, RuleGroupAssignment {
+    urlPattern: string;
+    eventType?: SSEEventTypeMatcher;
+    probability: number;
+}
+export interface SSEDelayConfig extends RequestCountingOptions, RuleGroupAssignment {
+    urlPattern: string;
+    eventType?: SSEEventTypeMatcher;
+    delayMs: number;
+    probability: number;
+}
+export interface SSECorruptConfig extends RequestCountingOptions, RuleGroupAssignment {
+    urlPattern: string;
+    eventType?: SSEEventTypeMatcher;
+    strategy: SSECorruptionStrategy;
+    probability: number;
+}
+export interface SSECloseConfig extends RequestCountingOptions, RuleGroupAssignment {
+    urlPattern: string;
+    /** Delay after `open` before dispatching `error` + closing, in ms. Default 0. */
+    afterMs?: number;
+    probability: number;
+}
+export interface SSEConfig {
+    drops?: SSEDropConfig[];
+    delays?: SSEDelayConfig[];
+    corruptions?: SSECorruptConfig[];
+    closes?: SSECloseConfig[];
+}
 export interface ChaosConfig {
     network?: NetworkConfig;
     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';
+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;
@@ -20,8 +41,37 @@ export interface ChaosEvent {
         closeCode?: number;
         /** WebSocket close reason (for `websocket:close` events). */
         closeReason?: string;
+        /** SSE event type (for `sse:*` events). `'message'` is the spec default. */
+        eventType?: string;
+        /** GraphQL operation name (for `network:*` events when the request was
+         *  detected as a GraphQL operation). Pivot on this to slice events by
+         *  operation in dashboards / assertions. */
+        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;
@@ -29,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/graphql.d.ts

@@ -0,0 +1,54 @@
+import type { GraphQLOperationMatcher } from './config';
+/** Result of attempting to extract a GraphQL operation from a request. */
+export type GraphQLExtractResult = {
+    kind: 'not-graphql';
+} | {
+    kind: 'extracted';
+    operationName: string | null;
+} | {
+    kind: 'unparseable';
+};
+/**
+ * Pull the operation name out of a GraphQL `query` string without bringing in
+ * a full GraphQL parser. Matches the first `query|mutation|subscription`
+ * keyword followed by an identifier — the spec form for named operations.
+ * Anonymous operations (`query { … }`) return `null`.
+ */
+export declare function parseOperationFromQueryString(query: string): string | null;
+/**
+ * Identify a request as GraphQL and extract its operation name.
+ *
+ * - `kind: 'extracted'` — request is GraphQL; `operationName` may be `null`
+ *   for anonymous operations.
+ * - `kind: 'not-graphql'` — not a GraphQL request (no body, wrong shape).
+ * - `kind: 'unparseable'` — looks like it could be GraphQL but the body is in
+ *   a form we can't read (multipart upload, ReadableStream, binary). Callers
+ *   that have a `graphqlOperation` matcher must skip the rule and emit a
+ *   diagnostic event so the user can debug why their rule isn't firing.
+ */
+export declare function extractGraphQLOperation(method: string, url: string, bodyText: string | null, bodyUnparseable: boolean): GraphQLExtractResult;
+/** Decide whether a rule's `graphqlOperation` matcher accepts the extracted name.
+ *
+ *  Defensive `lastIndex` reset: validation rejects `/g` and `/y` flags up-front,
+ *  but matchers can also be constructed dynamically (in-page, after deserialization),
+ *  so reset here too — `RegExp.test()` mutates `lastIndex` for stateful flags
+ *  and would flap match outcomes across consecutive calls with the same instance.
+ */
+export declare function operationNameMatches(matcher: GraphQLOperationMatcher, operationName: string | null): boolean;
+/** Outcome of evaluating a rule's `graphqlOperation` matcher against a request. */
+export type GraphQLRuleOutcome = {
+    kind: 'skip-no-constraint';
+    operationName: string | null;
+} | {
+    kind: 'match';
+    operationName: string | null;
+} | {
+    kind: 'no-match';
+} | {
+    kind: 'unparseable';
+};
+/**
+ * Evaluate a rule's `graphqlOperation` matcher against the cached extraction.
+ * `extract` is computed once per request and reused across all rules.
+ */
+export declare function evaluateGraphQLRule(matcher: GraphQLOperationMatcher | undefined, extract: GraphQLExtractResult): GraphQLRuleOutcome;

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>;
+}