feat: add SOXL core provenance optimizer

[Pigbibi]

Summary

• add the frozen SOXL-only SMA core optimizer with validation-only selection and R3 disposition gates
• bind publication to externally supplied current-HEAD commit/blob provenance and symlink-safe stdlib atomic persistence
• add provider-free regression coverage for core timing/parity, selection, provenance, and persistence safety

Validation

• PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src /Users/lisiyi/Projects/UsEquityStrategies/.venv/bin/python -m pytest -q tests/test_soxl_core_optimization.py tests/test_soxl_soxx_offline_input_contract.py tests/test_soxl_soxx_typed_baseline_result.py tests/test_r3_joint_evidence.py
• PYTHONDONTWRITEBYTECODE=1 /Users/lisiyi/Projects/UsEquityStrategies/.venv/bin/python -m compileall -q src/us_equity_strategies/research/soxl_core_optimization.py tests/test_soxl_core_optimization.py

No provider calls, data downloads, or real optimization/comparison runs were made.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 258b3d5062

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

🤖 Codex PR Review

✅ Merge allowed: 3 finding(s) reported but none are blocking

ℹ️ Other Findings

1. 🟡 [MEDIUM] Logic in src/us_equity_strategies/research/soxl_core_optimization.py

_typed_rows() only checks that source.input_digest matches a hex regex and never recomputes it from source.canonical_bytes. A caller can supply valid rows/canonical bytes plus an arbitrary 64-hex digest, and run_soxl_core_optimization() will still return evidence_valid=True and publish that forged input_digest, which breaks the audit trail for which dataset was actually optimized. (line 119)

Suggestion: Recompute the digest from source.canonical_bytes (or from the normalized rows) inside _typed_rows() and fail on mismatch, then emit the recomputed digest instead of trusting the caller-provided field.

2. 🟡 [MEDIUM] Reliability in src/us_equity_strategies/research/soxl_core_optimization.py

_write_set_once() publishes the bundle, sidecar, and readback files with three separate os.replace() calls after a lock-free existence check. A concurrent load_persisted_result() can observe a torn publication between those renames and fail with PERSISTED_FILE_MISSING/SIDECAR_MISMATCH, and two concurrent persist_result() calls can both pass the precheck and leave a mixed or overwritten file set instead of enforcing the advertised set-once semantics. (line 451)

Suggestion: Serialize writers around the existence check and publish sequence, and make readers rely on a single commit point (for example a final manifest/marker written only after all files are durable, or a single-file publication format).

3. 🟡 [MEDIUM] Reliability in src/us_equity_strategies/research/soxl_core_optimization.py

When output_root or one of its ancestors does not already exist, _ensure_output_root() creates directories with mkdir() but never fsync()s the parent directory entries. If the machine crashes after persist_result() returns, those newly created directories can be lost even though the files themselves were fsynced, so the function can report success without the publication being crash-durable. (line 421)

Suggestion: Track newly created directories and fsync() each parent after mkdir(), or require callers to provide a pre-created output root when durable persistence is required.

---

Review by Codex PR Review bot • PR