Redesign replay logging for audit/debug/replay and parallel runs

[matthewhorridge]

A redesign of the replay log is needed so it is actually useful for audit, debugging, and re-running, and so it remains safe when multiple harmonization runs happen in parallel.

Current behavior and gaps:

The replay logger is a global logger named “ReplayLogger” that clears handlers every time it’s configured, so parallel runs can interfere. The event format is minimal—only { action, dataset }—with no run metadata, schema version, timestamps, or before/after values. Logging occurs once per rule per dataset (before transform), which is insufficient for step-by-step replay or debugging. The replay helper in utils/transformations.py replays rules without preserving ordering across datasets, and the log does not record input/output paths or other audit-relevant metadata.

Why this matters:

A replay log should be self-contained, robust, and parallel-safe, and it should support auditing, debugging, and re-running. The current implementation does not.

Desired behavior:

• Replay log is self-contained and robust for audit/debug/re-run.
• Safe for multiple parallel runs (no shared global logger, no shared file).
• Includes input/output file paths and rules file path in metadata.
• Can optionally include before/after values (toggleable).
• Uses row identifiers (preferred) rather than row index.
• Schema version naming format: vN.N.N.
• Log is sufficient on its own for replay, though the rules file may exist.

Potential direction (not final):

• Introduce a per-run ReplayLogger class (no shared global handlers).
• One log file per run; fail if it already exists unless overwrite is allowed.
• JSONL schema with run_start, operation, and run_end events.
• operation events include dataset, rule serialization, row identifier, and optional before/after values.
• Update replay tool to use this schema and validate version.

Acceptance criteria:

• Parallel runs do not interfere.
• Log schema is versioned and documented.
• Tests cover overwrite behavior, optional before/after values, and replay parsing.

[matthewhorridge]

• Addendum (log level confusion):

The current numeric log level is misleading. configure_logger(level, ...) maps 1–4 to Python log levels, but log_operation() always logs at INFO. That means levels 1–2 silently log nothing, and only 3–4 actually write events. This doesn’t control replay detail, it just turns logging on/off in a non‑obvious way. The redesign should replace this with explicit replay logging options (e.g., enabled, include_before_after) rather than a numeric level.

[matthewhorridge]

Addendum (logger choice):

The Python logging module works for diagnostic logs, but it’s not ideal for a replay/audit artifact. Replay logs need deterministic, schema‑controlled output, strict ordering, explicit flush/close semantics, and no hidden global state. The standard logger API makes this awkward (global handlers, levels, formatting, buffering, append vs overwrite). A purpose‑built ReplayLogger that writes JSONL directly to a file handle is simpler and safer, especially for parallel runs.