fix(ci): correct stale -o path in explorer-extra-py311.txt header

Qodo review on this PR: the autogenerated header comment still said
-o .github/requirements/explorer-extra.txt (the pre-rename path), which
would silently regenerate the wrong file if someone copy-pasted it.

.dockerignore

@@ -19,7 +19,7 @@
 .github
 .github/**
 !.github/requirements/
-!.github/requirements/explorer-extra.txt
+!.github/requirements/explorer-extra-py313.txt
 !.github/requirements/pep517-build.txt
 .claude
 .claude/**

.github/requirements/README.md

@@ -7,8 +7,8 @@ These exist because OpenSSF Scorecard's Pinned-Dependencies check flags any
 `requirements-ci.txt` alone doesn't cover build/release/security tooling or
 the project's own local-source install.
 
-Each `.txt` was generated from the adjacent `.in` (or, for `explorer-extra.txt`
-and `base-deps.txt`, from `pyproject.toml` directly) with:
+Each `.txt` was generated from the adjacent `.in` (or, for `explorer-extra-py311.txt`,
+`explorer-extra-py313.txt`, and `base-deps.txt`, from `pyproject.toml` directly) with:
 
 ```
 uv pip compile <input> --python-version 3.11 --python-platform linux \
@@ -28,7 +28,8 @@ each file's own autogenerated header comment for its exact command).
 | --- | --- | --- |
 | `bootstrap.txt` | security.yml, security-scan.yml, benchmark.yml | pip, setuptools (upgrade before anything else) |
 | `pep517-build.txt` | ci.yml, benchmark.yml, Dockerfile | exact `[build-system] requires` from `pyproject.toml` (setuptools, wheel) - installed with `--no-build-isolation` before any `pip install -e .` / `pip install .`, since `--no-deps` alone doesn't stop pip's PEP 517 build isolation from fetching those two *unhashed* |
-| `explorer-extra.txt` | ci.yml, Dockerfile | semantica's base deps + the `explorer` extra |
+| `explorer-extra-py311.txt` | ci.yml | semantica's base deps + the `explorer` extra, resolved for python 3.11 |
+| `explorer-extra-py313.txt` | Dockerfile | the same, resolved for python 3.13 (the image's actual interpreter) |
 | `pytest-tool.txt` | ci.yml | pytest, for the pre-all-extras deterministic test |
 | `uv-tool.txt` | ci.yml | uv, to verify requirements-ci.txt is current |
 | `build-tools.txt` | ci.yml, release.yml | build, wheel |
@@ -38,7 +39,20 @@ each file's own autogenerated header comment for its exact command).
 | `base-deps.txt` | benchmark.yml | semantica's base deps (no extras) |
 | `benchmark-extra.txt` | benchmark.yml | the benchmark-only libs (neo4j, pdfplumber, etc.) |
 
-`explorer-extra.txt` and `base-deps.txt` are large (they mirror most of
-`requirements-ci.txt`) because semantica's `dependencies` list in
+`explorer-extra-py31{1,3}.txt` and `base-deps.txt` are large (they mirror
+most of `requirements-ci.txt`) because semantica's `dependencies` list in
 `pyproject.toml` isn't extras-gated - installing the package at all pulls
 the full base set. That's expected, not a mistake.
+
+`explorer-extra-py311.txt` and `explorer-extra-py313.txt` are **not**
+interchangeable, and can't be collapsed into one file compiled for either
+version: `librosa`'s `audioread` dependency needs `standard-aifc` /
+`standard-sunau` only under `python_version >= "3.13"` (Python 3.13 dropped
+`aifc`/`sunau` from stdlib). A file resolved for 3.11 simply omits those
+packages' hashes, so installing it with `--require-hashes` on a real 3.13
+interpreter (the Dockerfile's base image) fails outright rather than
+silently under-pinning. Any other file shared across a 3.11 and 3.13
+consumer would need the same split if it hits a similar stdlib-removal
+edge case - check for `ERROR: In --require-hashes mode, all requirements
+must have their versions pinned` on the *other* Python version before
+assuming one `--python-version` covers every consumer.

.github/requirements/explorer-extra-py311.txt

@@ -1,5 +1,5 @@
 # This file was autogenerated by uv via the following command:
-#    uv pip compile pyproject.toml --extra explorer --python-version 3.11 --python-platform linux --generate-hashes --constraint requirements-ci.txt -o .github/requirements/explorer-extra.txt
+#    uv pip compile pyproject.toml --extra explorer --python-version 3.11 --python-platform linux --generate-hashes --constraint requirements-ci.txt -o .github/requirements/explorer-extra-py311.txt
 annotated-doc==0.0.5 \
     --hash=sha256:117bac03a25ede5df5440e855b32d556049ca169ead221505badf432fed4b101 \
     --hash=sha256:c7e58ce09192557605d8bbd92836d7e1d520ac9580096042c0bfd197efacf1bb

.github/workflows/ci.yml

@@ -57,10 +57,13 @@ jobs:
           # `pip install -e ".[explorer]" pytest==9.1.1`) so every fetched
           # package is hash-verified (Scorecard Pinned-Dependencies); the
           # local editable install itself has nothing to hash.
-          # .github/requirements/explorer-extra.txt is
-          # `uv pip compile pyproject.toml --extra explorer --constraint requirements-ci.txt --generate-hashes`
+          # .github/requirements/explorer-extra-py311.txt is
+          # `uv pip compile pyproject.toml --extra explorer --python-version 3.11 --constraint requirements-ci.txt --generate-hashes`
           # - regenerate it the same way if pyproject.toml's base/explorer
-          # deps change.
+          # deps change. Resolved specifically for this job's python 3.11
+          # (see the Dockerfile's explorer-extra-py313.txt for why this
+          # can't be shared with python 3.13: audioread needs extra
+          # standard-aifc/standard-sunau hashes only on 3.13+).
           #
           # --no-deps only skips *runtime* dependency resolution - `-e .`
           # still does a PEP 517 build, which by default creates an isolated
@@ -71,7 +74,7 @@ jobs:
           # copies instead of fetching its own.
           pip install -r .github/requirements/pep517-build.txt --require-hashes
           pip install --no-deps --no-build-isolation -e .
-          pip install -r .github/requirements/explorer-extra.txt --require-hashes
+          pip install -r .github/requirements/explorer-extra-py311.txt --require-hashes
           pip install -r .github/requirements/pytest-tool.txt --require-hashes
       - name: Test deterministic Explorer backend path
         run: |

.github/workflows/container-scan.yml

@@ -12,7 +12,7 @@ on:
       - 'README.md'
       - 'LICENSE'
       - 'MANIFEST.in'
-      - '.github/requirements/explorer-extra.txt'
+      - '.github/requirements/explorer-extra-py313.txt'
       - '.github/requirements/pep517-build.txt'
       - 'semantica/**'
       - 'integrations/**'

Dockerfile

@@ -34,15 +34,21 @@ RUN groupadd --system semantica \
     && useradd --system --gid semantica --home-dir /app --shell /usr/sbin/nologin semantica
 
 COPY pyproject.toml README.md LICENSE MANIFEST.in \
-     .github/requirements/explorer-extra.txt .github/requirements/pep517-build.txt ./
+     .github/requirements/explorer-extra-py313.txt .github/requirements/pep517-build.txt ./
 COPY semantica/ ./semantica/
 COPY integrations/ ./integrations/
 COPY --from=frontend-builder /app/semantica/static ./semantica/static
 
-# explorer-extra.txt is `uv pip compile pyproject.toml --extra explorer
-# --constraint requirements-ci.txt --generate-hashes` (see ci.yml) - every
-# fetched package is hash-verified (Scorecard Pinned-Dependencies) and
-# pinned to the same versions CI audited, e.g. msgpack==1.2.1 and
+# explorer-extra-py313.txt is `uv pip compile pyproject.toml --extra explorer
+# --python-version 3.13 --constraint requirements-ci.txt --generate-hashes`
+# (see ci.yml's explorer-extra-py311.txt for the CI counterpart, resolved
+# for CI's python 3.11 instead - the two aren't interchangeable: audioread
+# (via librosa) needs standard-aifc/standard-sunau only on python>=3.13,
+# since aifc/sunau left stdlib there, so a 3.11-resolved lockfile is
+# missing hashes pip needs on this image's actual 3.13 interpreter and
+# --require-hashes fails outright rather than silently under-pinning).
+# Every fetched package is hash-verified (Scorecard Pinned-Dependencies)
+# and pinned to the same versions CI audited, e.g. msgpack==1.2.1 and
 # setuptools==84.0.0 (which also replaces the base image's vulnerable
 # 70.3.0, CVE-2025-47273 - nothing else in the tree pulls a newer copy).
 # --no-deps on the local package itself: it's our own source tree, not a
@@ -53,9 +59,9 @@ COPY --from=frontend-builder /app/semantica/static ./semantica/static
 # build-system.requires; installing it first and passing
 # --no-build-isolation makes pip reuse those hash-verified copies instead
 # of fetching its own.
-RUN pip install --no-cache-dir -r explorer-extra.txt -r pep517-build.txt --require-hashes \
+RUN pip install --no-cache-dir -r explorer-extra-py313.txt -r pep517-build.txt --require-hashes \
     && pip install --no-cache-dir --no-deps --no-build-isolation . \
-    && rm -f explorer-extra.txt pep517-build.txt \
+    && rm -f explorer-extra-py313.txt pep517-build.txt \
     && chown -R semantica:semantica /app
 
 USER semantica