Skip to content

engine

sqllocks_spindle.chaos.engine

Chaos Engine — the orchestrator that decides when and what to inject.

The engine owns the chaos RNG, evaluates per-day injection probabilities (respecting warmup, escalation curves, per-category weights, and intensity presets), and delegates to category-specific mutators.

Usage::

from sqllocks_spindle.chaos.config import ChaosConfig
from sqllocks_spindle.chaos.engine import ChaosEngine

cfg = ChaosConfig(enabled=True, intensity="stormy", seed=99)
engine = ChaosEngine(cfg)

if engine.should_inject(day=12, category="value"):
    df = engine.corrupt_dataframe(df, day=12)

Classes

ChaosEngine

Orchestrates chaos injection across all categories.

Parameters:

Name Type Description Default
config ChaosConfig | None

A :class:ChaosConfig instance controlling behaviour.

 None
seed int | None

If provided, overrides config.seed.

 None
Methods:
should_inject(day, category)

Decide whether chaos should fire on day for category.

Returns False immediately if the engine is disabled, the day is within the warmup window, or the category is disabled. Otherwise draws against the effective probability (base weight * intensity multiplier * escalation factor).

corrupt_dataframe(df, day)

Apply value-level chaos to a DataFrame.

Injects nulls, out-of-range values, wrong types, encoding issues, future dates, and negative amounts.

drift_schema(df, day)

Apply schema-level chaos: add/remove/rename/reorder/retype columns.

Destructive mutations (drop, rename) only fire after config.breaking_change_day.

corrupt_file(file_bytes, day)

Corrupt raw file bytes: truncation, encoding damage, partial writes, zero-byte, garbage headers.

inject_referential_chaos(tables_dict, day)

Corrupt referential integrity: orphan FKs, duplicate PKs.

inject_temporal_chaos(df, date_columns, day)

Corrupt temporal columns: late arrivals, out-of-order, timezone mismatches, DST boundary issues.

inject_volume_chaos(df, day)

Alter data volume: 10x spike, empty batch, or single-row.

apply_all(df, day, *, tables_dict=None, date_columns=None)

Run through every category and inject chaos where :meth:should_inject returns True.

This is a convenience wrapper — callers who need fine-grained control should call individual methods directly.