packs

sqllocks_spindle.packs

Scenario Pack system — load, validate, and run scenario packs.

Classes

FileDropSpec dataclass

File-drop landing zone specification.

FailureInjectionSpec dataclass

Failure injection specification.

HybridSpec dataclass

Hybrid (stream + micro-batch) specification.

PackLoader

Load scenario pack YAML files into ScenarioPack instances.

Methods:

load(path)

Load a scenario pack from an arbitrary YAML file path.

load_builtin(domain, pack_id)

Load a builtin scenario pack by domain and pack ID.

Example::

loader = PackLoader()
pack = loader.load_builtin("retail", "fd_daily_batch")

list_builtin()

Return metadata for all available builtin packs.

Returns a list of dicts with keys: domain, pack_id, path.

ScenarioPack dataclass

Complete scenario pack definition loaded from YAML.

Attributes

entities property

Return the list of entities referenced in this pack.

topics property

Return the list of stream topics referenced in this pack.

StreamSpec dataclass

Streaming specification.

ValidationSpec dataclass

Validation gate configuration.

PackValidator

Validate a ScenarioPack against a domain's schema.

Checks that entities referenced in the pack exist in the domain, event types are plausible, and paths are well-formed.

Methods:

validate(pack, domain)

Validate a pack against the given domain instance.

Parameters:

Name	Type	Description	Default
pack	ScenarioPack	The scenario pack to validate.	required
domain	Any	A Domain instance (e.g., RetailDomain()) whose schema provides the ground truth for entity/table names.	required

Returns:

Type	Description
PackValidationResult	PackValidationResult with errors and warnings.

PackValidationResult dataclass

Result of validating a scenario pack against a domain.

PackRunner

Orchestrate a complete scenario pack execution.

Steps

1. Validate pack against domain schema
2. Generate base data via Spindle engine
3. Run simulation (file_drop / stream / hybrid)
4. Validate outputs against gates
5. Emit run manifest

Methods:

run(pack, domain, scale='small', seed=42, base_path='.')

Execute a scenario pack end-to-end.

Parameters:

Name	Type	Description	Default
pack	ScenarioPack	The ScenarioPack to execute.	required
domain	Any	A Domain instance whose schema drives generation.	required
scale	str	Scale preset (small, medium, large, xlarge).	'small'
seed	int	Random seed for reproducibility.	42
base_path	str	Root directory for output files.	'.'

Returns:

Type	Description
RunResult	RunResult with manifest, files written, and validation outcomes.

RunResult dataclass

Result of a complete scenario pack execution.