quarantine

sqllocks_spindle.validation.quarantine

Quarantine manager for failed validation artifacts.

Classes

QuarantineEntry dataclass

Metadata for a single quarantined artifact.

QuarantineManager

Move or copy failed artifacts to a quarantine directory.

Quarantine directory layout::

<quarantine_root>/<domain>/<run_id>/
    <filename>
    <filename>._quarantine_meta.json

Methods:

quarantine_file(source_path, quarantine_root, run_id, reason, gate_name='unknown')

Copy a file into the quarantine directory with metadata.

Returns the path to the quarantined copy.

quarantine_dataframe(df, quarantine_root, run_id, table_name, reason, gate_name='unknown', fmt='parquet')

Write a DataFrame to quarantine with metadata.

Parameters:

Name	Type	Description	Default
df	DataFrame	The DataFrame to quarantine.	required
quarantine_root	str | Path	Root quarantine directory.	required
run_id	str	Unique identifier for the generation run.	required
table_name	str	Logical table name.	required
reason	str	Why this artifact was quarantined.	required
gate_name	str	Which validation gate triggered quarantine.	'unknown'
fmt	str	Output format — "parquet", "csv", or "jsonl".	'parquet'

Returns the path to the quarantined file.

list_quarantined(quarantine_root)

List all quarantined items across all domains and runs.

Returns a list of dicts with quarantine metadata.

get_quarantine_report(quarantine_root, run_id)

Get a detailed report for a specific run's quarantined artifacts.

Returns a dict with run-level summary and per-artifact details.