[codex] clarify QSL pin manifests

.github/workflows/ci.yml

@@ -36,11 +36,16 @@ jobs:
           import tempfile
           from pathlib import Path
 
+          constraint_path = Path("qsl-pins.txt")
+          if not constraint_path.exists():
+              constraint_path = Path("constraints.txt")
+          print(f"Validating dependency refs from {constraint_path}")
+
           pattern = re.compile(
               r"^(?P<package>[A-Za-z0-9_.-]+)\s+@\s+git\+(?P<url>https://github\.com/QuantStrategyLab/[^@]+\.git)@(?P<ref>[A-Za-z0-9_.-]+)\s*$"
           )
           failures = []
-          for line in Path("constraints.txt").read_text(encoding="utf-8").splitlines():
+          for line in constraint_path.read_text(encoding="utf-8").splitlines():
               stripped = line.strip()
               if not stripped or stripped.startswith("#"):
                   continue

.github/workflows/update-qpk-pin.yml

@@ -5,6 +5,7 @@ on:
     branches: [ main ]
     paths-ignore:
       - "QPK_PIN"
+      - "qsl-pins.txt"
       - "constraints.txt"
       - "docs/**"
       - "**.md"
@@ -25,7 +26,7 @@ jobs:
         with:
           python-version: "3.11"
 
-      - name: Update QPK_PIN and constraints
+      - name: Update QPK_PIN and pin manifests
         id: update
         run: |
           SHA=$(git rev-parse HEAD)
@@ -39,8 +40,12 @@ jobs:
             pkg="${pair%%:*}"
             repo="${pair##*:}"
             RSHA=$(git ls-remote "https://github.com/QuantStrategyLab/$repo.git" HEAD | cut -f1)
-            [ -n "$RSHA" ] && sed -i "s|$pkg @ git+https://github.com/QuantStrategyLab/$repo.git@[a-f0-9]*|$pkg @ git+https://github.com/QuantStrategyLab/$repo.git@$RSHA|" constraints.txt || true
+            if [ -n "$RSHA" ]; then
+              sed -i "s|$pkg @ git+https://github.com/QuantStrategyLab/$repo.git@[a-f0-9]*|$pkg @ git+https://github.com/QuantStrategyLab/$repo.git@$RSHA|" qsl-pins.txt
+              sed -i "s|$pkg @ git+https://github.com/QuantStrategyLab/$repo.git@[a-f0-9]*|$pkg @ git+https://github.com/QuantStrategyLab/$repo.git@$RSHA|" constraints.txt
+            fi
           done
+          sed -i "s|quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@[a-f0-9]*|quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@$SHA|" qsl-pins.txt
           sed -i "s|quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@[a-f0-9]*|quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@$SHA|" constraints.txt
 
           if git diff --quiet; then
@@ -72,10 +77,11 @@ jobs:
           # would conflict until downstream repos update those pins, so keep this
           # check focused on the package refs generated above.
           failed=0
+          pin_file="qsl-pins.txt"
           for dep in us-equity-strategies hk-equity-strategies cn-equity-strategies crypto-strategies; do
             echo "Checking $dep..."
             log_file="$(mktemp)"
-            if python -m pip install --dry-run --no-deps -c constraints.txt "$dep" >"${log_file}" 2>&1; then
+            if python -m pip install --dry-run --no-deps -c "$pin_file" "$dep" >"${log_file}" 2>&1; then
               echo "  $dep OK"
             else
               echo "  $dep FAILED"
@@ -98,10 +104,10 @@ jobs:
         uses: peter-evans/create-pull-request@v7
         with:
           token: ${{ github.token }}
-          commit-message: "chore: auto-update QPK_PIN and constraints.txt"
-          title: "chore: auto-update QPK_PIN and constraints.txt"
+          commit-message: "chore: auto-update QPK_PIN and pin manifests"
+          title: "chore: auto-update QPK_PIN and pin manifests"
           body: |
-            Automated update of QPK_PIN and dependency constraint SHAs.
+            Automated update of QPK_PIN and QSL Git SHA pin manifests.
 
             Compatibility checks passed ✅ — all downstream-critical QPK modules verified importable.
 
@@ -120,7 +126,7 @@ jobs:
           cat >> "$GITHUB_STEP_SUMMARY" <<'MD'
           ## QPK pin update PR not created
 
-          The generated `QPK_PIN` / `constraints.txt` update was verified, but repository policy prevented `GITHUB_TOKEN` from creating a pull request.
+          The generated `QPK_PIN` / `qsl-pins.txt` / `constraints.txt` update was verified, but repository policy prevented `GITHUB_TOKEN` from creating a pull request.
 
           Manual follow-up:
           - Enable the repository setting that allows GitHub Actions to create pull requests, or

constraints.txt

@@ -1,5 +1,5 @@
-# QSL Dependency Constraints — SINGLE SOURCE OF TRUTH
-# Auto-updated by update-qpk-pin.yml on every push to QPK main.
+# pip-compatible constraints mirror for QSL internal Git SHA pins.
+# Source of truth: qsl-pins.txt (mirrored by update-qpk-pin.yml on every push to QPK main).
 
 quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@d3a629f82f6dbb6c11488ae15c0c66f368c19f5b
 us-equity-strategies @ git+https://github.com/QuantStrategyLab/UsEquityStrategies.git@4041018434a5a83597d8798faee98f650362de0d

qsl-pins.txt

@@ -0,0 +1,8 @@
+# QSL internal Git SHA pins — source of truth.
+# Auto-updated by update-qpk-pin.yml on every push to QPK main.
+
+quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@d3a629f82f6dbb6c11488ae15c0c66f368c19f5b
+us-equity-strategies @ git+https://github.com/QuantStrategyLab/UsEquityStrategies.git@4041018434a5a83597d8798faee98f650362de0d
+hk-equity-strategies @ git+https://github.com/QuantStrategyLab/HkEquityStrategies.git@f48acb8ed6de3c6bff13bf941fef1c8a6969b07d
+cn-equity-strategies @ git+https://github.com/QuantStrategyLab/CnEquityStrategies.git@f8d35fb15c3ca13589a98ab7df0c7db6172f917d
+crypto-strategies @ git+https://github.com/QuantStrategyLab/CryptoStrategies.git@c6b0c2d013e0336668752c9d8b1eade660ab8773

qsl.toml

@@ -1,7 +1,7 @@
 tier = "core"
 ring = 0
 allow_legacy = true
-legacy_reason = "constraints.txt remains for pinned downstream git deps and update-qpk-pin workflow."
+legacy_reason = "constraints.txt remains as the pip-compatible mirror for qsl-pins.txt and update-qpk-pin workflow."
 
 [compat]
 bundle = "2026.07.1"

tests/test_qsl_pin_manifests.py

@@ -0,0 +1,21 @@
+from pathlib import Path
+
+
+def _pin_lines(path: Path) -> list[str]:
+    return [
+        line.strip()
+        for line in path.read_text(encoding="utf-8").splitlines()
+        if line.strip() and not line.lstrip().startswith("#")
+    ]
+
+
+def test_qsl_pin_manifests_are_kept_in_sync() -> None:
+    root = Path(__file__).resolve().parents[1]
+    pins = root / "qsl-pins.txt"
+    constraints = root / "constraints.txt"
+
+    assert pins.exists(), "qsl-pins.txt missing"
+    assert constraints.exists(), "constraints.txt missing"
+    assert "source of truth" in pins.read_text(encoding="utf-8")
+    assert "pip-compatible constraints mirror" in constraints.read_text(encoding="utf-8")
+    assert _pin_lines(pins) == _pin_lines(constraints)