merge: audit-fix-f-ci into chore/cleanup-session-plus-8 (Phase F round 1+2+3+4 CONVERGED)

Author: zhmiao

.github/workflows/release.yml

@@ -70,12 +70,170 @@ jobs:
       - name: Verify installer/*.ps1 files start with UTF-8 BOM if non-ASCII
         run: python3 installer/check_ps1_bom.py
 
+  # ---------------------------------------------------------------------------
+  # Preflight: version consistency guard (Phase F audit-fix round 1, B-03).
+  #
+  # Asserts at tag-push time that the three version sources agree:
+  #   1. git tag                                  (refs/tags/vX.Y.Z, stripped 'v')
+  #   2. sparrow-engine-cli/Cargo.toml            ([package].version — the source `spe --version` reads via CARGO_PKG_VERSION at sparrow-engine-cli/src/main.rs:43)
+  #   3. sparrow-engine-python/pyproject.toml     ([project].version — the source the PyPI wheel METADATA carries)
+  #
+  # All three MUST equal each other before any wheel / CLI tarball build starts.
+  # A mismatch means the tag was cut without bumping one of the manifests, which
+  # would either (a) ship a wheel whose METADATA disagrees with PyPI's stored
+  # version (publish-pypi-cpu's existing tag-vs-wheel check would catch THAT but
+  # too late — the GPU build also runs unnecessarily) or (b) ship a CLI tarball
+  # whose `spe --version` output disagrees with the wheel users see in `pip show`.
+  #
+  # Surfaced by Phase 4.5 lane 1 finding L1-F5 (MT-4.5-97/-98/-102): `spe --version`
+  # reported `0.1.0` while PyPI shipped 0.1.12 and brew shipped 0.1.10. Once Phase D
+  # bumps sparrow-engine-cli/Cargo.toml in lockstep with pyproject.toml, this guard
+  # prevents future drift.
+  #
+  # Gated to tag-push: workflow_dispatch / push-to-branch don't carry a tag-name
+  # commitment so the comparison is N/A and the job no-ops (skipped by `if:`).
+  # This means downstream `needs:` lists can include this job without slowing
+  # non-release runs.
+  # ---------------------------------------------------------------------------
+  check-version-consistency:
+    name: Preflight — version consistency (tag ↔ Cargo.toml ↔ pyproject.toml)
+    # Runs on every trigger. The internal step short-circuits with a PASS
+    # message on non-tag-push triggers so downstream `needs:` are unambiguously
+    # satisfied across workflow_dispatch / branch-push / tag-push. (Relying on
+    # GitHub's "skipped jobs satisfy needs" implicit rule is fragile when the
+    # downstream's own `if:` interacts with needs.* results.)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Compare git tag, sparrow-engine-cli Cargo.toml, sparrow-engine-python pyproject.toml
+        shell: bash
+        run: |
+          set -euo pipefail
+          # Trigger taxonomy (Phase F R2 F-R2-4):
+          #   tag-push       : enforce tag ↔ cli ↔ py three-way agreement (release-critical).
+          #   workflow_dispatch: enforce cli ↔ py two-way agreement (manual release rehearsal
+          #                     — no tag yet, but Cargo/Python must already agree so a follow-up
+          #                     tag-push doesn't blow up).
+          #   branch-push / PR: skip (most common dev case; pre-tag drift is intentional and
+          #                     gets caught at workflow_dispatch / tag-push time).
+          mode=""
+          if [ "${GITHUB_EVENT_NAME}" = "push" ] && [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
+            mode="tag-push"
+          elif [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ]; then
+            mode="workflow-dispatch"
+          else
+            echo "Non-release trigger (event=${GITHUB_EVENT_NAME}, ref=${GITHUB_REF}). Skipping check."
+            exit 0
+          fi
+          echo "Enforcement mode: $mode"
+          # Strip optional leading 'v' from the tag name. Empty string on
+          # workflow_dispatch (no tag context); tag-version comparisons below
+          # are gated on `mode == tag-push` so the empty value is never read
+          # for enforcement in that path.
+          tag_version=""
+          if [ "$mode" = "tag-push" ]; then
+            tag_version="${GITHUB_REF_NAME#v}"
+          fi
+
+          # sparrow-engine-cli Cargo.toml [package].version — awk-extracted (no python heredoc,
+          # no cargo / jq install). Looks for the `version = "..."` line under the `[package]`
+          # section header, stops at the next `[…]` section.
+          cli_version="$(awk '
+            /^\[package\][[:space:]]*$/      { in_pkg = 1; next }
+            in_pkg && /^\[/                  { in_pkg = 0 }
+            in_pkg && /^version[[:space:]]*=/{ match($0, /"[^"]+"/); print substr($0, RSTART+1, RLENGTH-2); exit }
+          ' sparrow-engine/sparrow-engine-cli/Cargo.toml)"
+          if [ -z "$cli_version" ]; then
+            echo "::error::could not extract [package].version from sparrow-engine/sparrow-engine-cli/Cargo.toml"
+            exit 2
+          fi
+
+          # sparrow-engine-python pyproject.toml [project].version — same awk pattern against [project].
+          py_version="$(awk '
+            /^\[project\][[:space:]]*$/      { in_proj = 1; next }
+            in_proj && /^\[/                 { in_proj = 0 }
+            in_proj && /^version[[:space:]]*=/{ match($0, /"[^"]+"/); print substr($0, RSTART+1, RLENGTH-2); exit }
+          ' sparrow-engine/sparrow-engine-python/pyproject.toml)"
+          if [ -z "$py_version" ]; then
+            echo "::error::could not extract [project].version from sparrow-engine/sparrow-engine-python/pyproject.toml"
+            exit 2
+          fi
+
+          echo "Tag version (stripped 'v'):           ${tag_version:-<n/a — workflow_dispatch>}"
+          echo "sparrow-engine-cli Cargo.toml:        $cli_version"
+          echo "sparrow-engine-python pyproject.toml: $py_version"
+
+          fail=0
+          if [ "$mode" = "tag-push" ]; then
+            if [ "$tag_version" != "$cli_version" ]; then
+              echo "::error::tag ($tag_version) ≠ sparrow-engine-cli Cargo.toml ($cli_version)"
+              echo "  -> bump sparrow-engine/sparrow-engine-cli/Cargo.toml [package].version to '$tag_version' before re-tagging."
+              fail=1
+            fi
+            if [ "$tag_version" != "$py_version" ]; then
+              echo "::error::tag ($tag_version) ≠ sparrow-engine-python pyproject.toml ($py_version)"
+              echo "  -> bump sparrow-engine/sparrow-engine-python/pyproject.toml [project].version to '$tag_version' before re-tagging."
+              fail=1
+            fi
+          fi
+          # cli ↔ py agreement is enforced on BOTH tag-push and workflow_dispatch
+          # (F-R2-4 round-2 fix): a workflow_dispatch release rehearsal must surface
+          # version drift before tag-push time, otherwise the manual dispatch path
+          # gives false-PASS while the eventual tag still fails.
+          if [ "$cli_version" != "$py_version" ]; then
+            echo "::error::sparrow-engine-cli Cargo.toml ($cli_version) ≠ sparrow-engine-python pyproject.toml ($py_version)"
+            fail=1
+          fi
+          if [ "$fail" -ne 0 ]; then
+            echo ""
+            echo "FAIL: version consistency guard (Phase F B-03)."
+            echo "Refs: docs/review/phase4.5-cleanup-audit-fix-f/round_01/reviewer_review.md § B-03"
+            echo "      docs/review/phase4.5-cleanup-audit-fix-f/round_02/fixer_report.md § F-R2-4"
+            exit 1
+          fi
+          if [ "$mode" = "tag-push" ]; then
+            echo "PASS: all three version sources agree on '$tag_version'."
+          else
+            echo "PASS (workflow_dispatch): cli ↔ py agree on '$cli_version' (tag check skipped — no tag context)."
+          fi
+
+      - name: Compare ORT_VERSION across Dockerfile.cpu and Dockerfile.gpu
+        shell: bash
+        run: |
+          set -euo pipefail
+          # F-R2-6 (round 2): ARG ORT_VERSION is duplicated across the two
+          # Dockerfiles. A future ORT bump must touch both atomically or the
+          # CPU and GPU images drift into different ORT runtimes — which is
+          # the exact root cause B-06/B-07 fixed in round 1. Cheap grep guard
+          # in CI is simpler than refactoring to a shared build-arg source.
+          cpu_ort="$(awk '/^ARG[[:space:]]+ORT_VERSION=/{
+            sub(/^ARG[[:space:]]+ORT_VERSION=/, ""); print; exit
+          }' sparrow-engine/docker/Dockerfile.cpu)"
+          gpu_ort="$(awk '/^ARG[[:space:]]+ORT_VERSION=/{
+            sub(/^ARG[[:space:]]+ORT_VERSION=/, ""); print; exit
+          }' sparrow-engine/docker/Dockerfile.gpu)"
+          if [ -z "$cpu_ort" ] || [ -z "$gpu_ort" ]; then
+            echo "::error::could not extract ARG ORT_VERSION from one or both Dockerfiles"
+            echo "  Dockerfile.cpu: '${cpu_ort:-<missing>}'"
+            echo "  Dockerfile.gpu: '${gpu_ort:-<missing>}'"
+            exit 2
+          fi
+          echo "Dockerfile.cpu ARG ORT_VERSION: $cpu_ort"
+          echo "Dockerfile.gpu ARG ORT_VERSION: $gpu_ort"
+          if [ "$cpu_ort" != "$gpu_ort" ]; then
+            echo "::error::ARG ORT_VERSION drift: Dockerfile.cpu=$cpu_ort, Dockerfile.gpu=$gpu_ort"
+            echo "  -> bump both Dockerfiles atomically; ORT-side ABI must match across CPU and GPU images."
+            echo "  Refs: docs/review/phase4.5-cleanup-audit-fix-f/round_02/fixer_report.md § F-R2-6"
+            exit 1
+          fi
+          echo "PASS: Dockerfile.cpu and Dockerfile.gpu agree on ORT_VERSION=$cpu_ort."
+
   # -------- CPU build matrix --------
 
   build-cpu-linux:
     name: Build CPU wheel (Linux manylinux_2_28 x86_64)
     runs-on: ubuntu-latest
-    needs: check-installer-ps1-bom
+    needs: [check-installer-ps1-bom, check-version-consistency]
     steps:
       - uses: actions/checkout@v4
 
@@ -156,7 +314,7 @@ jobs:
   build-cpu-macos-arm64:
     name: Build CPU wheel (macOS arm64)
     runs-on: macos-14
-    needs: check-installer-ps1-bom
+    needs: [check-installer-ps1-bom, check-version-consistency]
     env:
       MACOSX_DEPLOYMENT_TARGET: '11.0'
     steps:
@@ -199,7 +357,7 @@ jobs:
   build-cpu-windows:
     name: Build CPU wheel (Windows x86_64)
     runs-on: windows-latest
-    needs: check-installer-ps1-bom
+    needs: [check-installer-ps1-bom, check-version-consistency]
     steps:
       - uses: actions/checkout@v4
 
@@ -243,7 +401,7 @@ jobs:
   build-gpu-linux:
     name: Build GPU wheel (Linux x86_64, CUDA 12.6 + cuDNN, Rocky 8 / glibc 2.28)
     runs-on: ubuntu-latest
-    needs: check-installer-ps1-bom
+    needs: [check-installer-ps1-bom, check-version-consistency]
     container:
       # Rocky 8 base = RHEL 8 clone = glibc 2.28 (the manylinux_2_28 floor).
       # Phase F (2026-05-25): swapped from ubuntu24.04 (glibc 2.39) so the
@@ -338,7 +496,7 @@ jobs:
   build-gpu-windows:
     name: Build GPU wheel (Windows x86_64)
     runs-on: windows-latest
-    needs: check-installer-ps1-bom
+    needs: [check-installer-ps1-bom, check-version-consistency]
     # No CUDA Toolkit on the runner. cudarc's `fallback-dynamic-loading`
     # feature (vendor/cudarc/build.rs:70-78) activates the `dynamic-loading`
     # cfg from the feature flag alone, with no nvcc / driver probing.
@@ -607,7 +765,7 @@ jobs:
   build-cli-linux-cpu:
     name: Build CLI tarball (sparrow-engine-cpu, Linux x86_64)
     runs-on: ubuntu-latest
-    needs: check-installer-ps1-bom
+    needs: [check-installer-ps1-bom, check-version-consistency]
     container:
       # manylinux_2_28 = glibc 2.28 floor, matches build-cpu-linux's wheel target.
       image: quay.io/pypa/manylinux_2_28_x86_64
@@ -671,7 +829,7 @@ jobs:
   build-cli-linux-gpu:
     name: Build CLI tarball (sparrow-engine-gpu, Linux x86_64)
     runs-on: ubuntu-latest
-    needs: check-installer-ps1-bom
+    needs: [check-installer-ps1-bom, check-version-consistency]
     container:
       # Same Rocky 8 / glibc 2.28 image as build-gpu-linux.
       image: nvidia/cuda:12.6.3-cudnn-devel-rockylinux8
@@ -761,7 +919,7 @@ jobs:
   build-cli-macos-arm64:
     name: Build CLI tarball (sparrow-engine-cpu, macOS arm64)
     runs-on: macos-14
-    needs: check-installer-ps1-bom
+    needs: [check-installer-ps1-bom, check-version-consistency]
     env:
       MACOSX_DEPLOYMENT_TARGET: '11.0'
     steps:
@@ -825,7 +983,7 @@ jobs:
   build-cli-windows:
     name: Build CLI tarball (sparrow-engine-cpu, Windows x86_64)
     runs-on: windows-latest
-    needs: check-installer-ps1-bom
+    needs: [check-installer-ps1-bom, check-version-consistency]
     steps:
       - uses: actions/checkout@v4
 

sparrow-engine/CHANGELOG.md

@@ -8,6 +8,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **Phase 4.5 audit-fix Phase F (CI + Docker + release plumbing) — Round 1**
+  2026-05-28 (HEAD `3052a70`, `6c6bbaf`); Round 2 hardening 2026-05-28.
+  - **B-03**: new `check-version-consistency` preflight job in `.github/workflows/release.yml`
+    enforces `git tag ↔ sparrow-engine-cli/Cargo.toml [package].version ↔
+    sparrow-engine-python/pyproject.toml [project].version` agreement on tag-push.
+    Round 2 (F-R2-4) extended enforcement to `workflow_dispatch` for the cli ↔ py pair
+    so manual release rehearsals catch drift before tag-push time. All 8 release build
+    jobs gain `needs: check-version-consistency`. `scripts/package_cli_tarball.sh`
+    defaults VERSION from `cargo metadata` on `sparrow-engine-cli/Cargo.toml` when the
+    caller doesn't set it, anchoring the tarball name on the same SSOT.
+  - **B-04**: PyPI wheels (`sparrow-engine`, `sparrow-engine-gpu`) are decided Python-API
+    only — the CLI binaries (`spe`, `spe-gpu`) and `sparrow-engine-server` do NOT ship
+    via `pip`. Decision rationale in `sparrow-engine-python/pyproject.toml` `[tool.maturin]`
+    comment (3 alternatives investigated, rejected on wheel-size + per-platform-binary
+    grounds). Round 2 (F-R2-2) extended `[project].description` with the warning so the
+    routing is visible on the PyPI project page; install via brew, system installer
+    (`sparrow-engine-install.{sh,ps1}`), or GitHub Release tarball.
+  - **B-06**: CPU Docker image (`docker/Dockerfile.cpu`) — bumped `ARG ORT_VERSION`
+    from `1.24.2` → `1.25.1` (aligns with `onnxruntime>=1.25.1,<1.26` pin in
+    `pyproject.toml` and the `api-24` ORT API the `sparrow-engine-cpu` Rust binding
+    requires post commit `5c86dbf`). Added
+    `RUN ln -sf libonnxruntime.so.1 /usr/local/lib/libonnxruntime.so && ldconfig`
+    after the existing `RUN ldconfig` so `dlopen("libonnxruntime.so")` (bare unversioned
+    name emitted by `ort/load-dynamic` when `ORT_DYLIB_PATH` is unset) resolves via
+    `/usr/local/lib` filesystem search. Symlink anchored on the ldconfig-managed SONAME
+    `libonnxruntime.so.1` — version-bump-resilient.
+  - **B-07**: GPU Docker image (`docker/Dockerfile.gpu`) — same ORT bump `1.24.2` →
+    `1.25.1` (root cause identical to B-06: `api-24` Rust binding ↔ ORT 1.24.2 runtime
+    mismatch caused the GPU server to boot and list models, then silently spin on the
+    first CUDA EP / Session creation call). Same defensive
+    `ln -sf libonnxruntime.so.1 /usr/local/lib/libonnxruntime.so && ldconfig` for parity
+    with B-06. Round 2 verified end-to-end via CPU + GPU image rebuilds + `/healthz` +
+    `/v1/health` smoke
+    + GPU `POST /v1/detect` against MDv6 — see
+    `docs/review/phase4.5-cleanup-audit-fix-f/round_02/docker_smoke_results.txt`.
+  - **F-R2-6** (round 2): new `check-version-consistency` step asserts
+    `ARG ORT_VERSION` matches across `Dockerfile.cpu` and `Dockerfile.gpu`. Cheap grep
+    guard against future ORT-bump drift (root cause family for B-06/B-07).
+  - **build.sh / package_cli_tarball.sh observability** (round 1 `6c6bbaf`):
+    `build.sh` post-build prints `[project.scripts]` entry-point names extracted from
+    the built wheel via `wheel unpack` (returns 0 on absence — pure diagnostic).
+    `package_cli_tarball.sh` defaults `VERSION` from `cargo metadata` when unset
+    (CI callers pass explicit VERSION; the default keeps local invocations consistent).
+
 ### Changed
 
 - **Phase 4 (Sparrow Engine-side data primitives for sibling integration) substantively complete**

sparrow-engine/docker/Dockerfile.cpu

@@ -23,8 +23,15 @@ COPY sparrow-engine-cli/ sparrow-engine-cli/
 COPY sparrow-engine-python/ sparrow-engine-python/
 COPY vendor/ vendor/
 
-# Download ORT shared library (dynamic linking avoids glibc 2.38+ requirement of static builds)
-ARG ORT_VERSION=1.24.2
+# Download ORT shared library (dynamic linking avoids glibc 2.38+ requirement of static builds).
+#
+# Phase F audit-fix round 1 (2026-05-28, B-06): bumped 1.24.2 -> 1.25.1.
+# Phase 3.8 Phase C commit 5c86dbf added `ort/load-dynamic` + `api-24` features to
+# `sparrow-engine-cpu/Cargo.toml`. `api-24` targets ORT runtime 1.25.x; the older
+# 1.24.2 tarball is API-incompatible and either silently spins or aborts at first
+# ORT call. Aligning the Docker ORT to the same `>=1.25.1,<1.26` pin the Python wheel
+# carries (sparrow-engine-python/pyproject.toml) keeps every consumer on one ORT major.minor.
+ARG ORT_VERSION=1.25.1
 RUN mkdir -p /build/ort-lib && \
     curl -sL https://github.com/microsoft/onnxruntime/releases/download/v${ORT_VERSION}/onnxruntime-linux-x64-${ORT_VERSION}.tgz | \
     tar xz --strip-components=1 -C /build/ort-lib
@@ -45,6 +52,17 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 COPY --from=builder /build/target/release/sparrow-engine-server /usr/local/bin/
 COPY --from=builder /build/ort-lib/lib/libonnxruntime.so* /usr/local/lib/
 RUN ldconfig
+# Phase F audit-fix round 1 (2026-05-28, B-06): `sparrow-engine-server` is built with
+# `ort/load-dynamic` (sparrow-engine-cpu/Cargo.toml:14). The Rust binding dlopens the
+# bare unversioned name `libonnxruntime.so` when `ORT_DYLIB_PATH` is unset. `ldconfig`
+# above only indexes the SONAME `libonnxruntime.so.1` -> `libonnxruntime.so.1.25.1`;
+# the unversioned name has no `/etc/ld.so.cache` entry and the regular file copied by
+# the wildcard COPY above is invisible to dlopen-by-name lookup. Adding an explicit
+# symlink anchored on the ldconfig-managed SONAME makes the bare-name dlopen succeed
+# without ENV LD_LIBRARY_PATH or ENV ORT_DYLIB_PATH workarounds, and survives future
+# `ARG ORT_VERSION` bumps unchanged.
+# Refs: Phase C Lane 3 finding F2 (LD_DEBUG=libs trace) + Phase F reviewer_review.md B-06.
+RUN ln -sf libonnxruntime.so.1 /usr/local/lib/libonnxruntime.so && ldconfig
 
 RUN groupadd -g 1000 sparrow-engine 2>/dev/null || true && useradd -u 1000 -g 1000 -s /sbin/nologin sparrow-engine 2>/dev/null || true
 USER 1000:1000