openretailscience 0.46.0__tar.gz → 0.48.0__tar.gz

openretailscience-0.48.0/.env_sample

@@ -0,0 +1,9 @@
+GCP_PROJECT_ID=
+
+# Snowflake CI Configuration (for integration tests)
+SNOWFLAKE_CI_ACCOUNT=
+SNOWFLAKE_CI_USER=
+SNOWFLAKE_CI_WAREHOUSE=
+SNOWFLAKE_CI_DATABASE=
+SNOWFLAKE_CI_SCHEMA=
+SNOWFLAKE_CI_PRIVATE_KEY_PATH=

{openretailscience-0.46.0 → openretailscience-0.48.0}/.github/dependabot.yml

@@ -5,6 +5,8 @@ updates:
     schedule:
       interval: "weekly"
     open-pull-requests-limit: 5
+    cooldown:
+      default-days: 7
     commit-message:
       prefix: "chore(deps)"
       prefix-development: "chore(deps-dev)"
@@ -13,3 +15,16 @@ updates:
         dependency-type: "production"
       development-dependencies:
         dependency-type: "development"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    cooldown:
+      default-days: 7
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      actions-minor-patch:
+        update-types: ["minor", "patch"]

openretailscience-0.48.0/.github/workflows/bigquery-integration.yml

@@ -0,0 +1,48 @@
+name: BigQuery Integration Tests
+
+on:
+  workflow_dispatch:
+  workflow_call:
+    secrets:
+      GCP_SA_KEY:
+        required: true
+      GCP_PROJECT_ID:
+        required: true
+
+permissions:
+  contents: read
+
+jobs:
+  integration-tests:
+    name: Run BigQuery Integration Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Setup Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+
+      - name: Install Dependencies
+        run: |
+          uv sync --locked
+
+      - name: Set up GCP Authentication
+        uses: google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093 # v3.0.0
+        with:
+          credentials_json: ${{ secrets.GCP_SA_KEY }}
+
+      - name: Run Integration Tests
+        env:
+          GCP_PROJECT_ID: ${{ secrets.GCP_PROJECT_ID }}
+        run: |
+          uv run pytest tests/integration -k "bigquery" -v

{openretailscience-0.46.0 → openretailscience-0.48.0}/.github/workflows/claude-code-review.yml

@@ -18,6 +18,9 @@ jobs:
     #   github.event.pull_request.user.login == 'new-developer' ||
     #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
 
+    # Skip automated dependency PRs: Dependabot runs without access to secrets and
+    # claude-code-action refuses to run for bot actors, so the job can only ever fail.
+    if: github.actor != 'dependabot[bot]'
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -27,13 +30,14 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 1
+          persist-credentials: false
 
       - name: Run Claude Code Review
         id: claude-review
-        uses: anthropics/claude-code-action@v1
+        uses: anthropics/claude-code-action@b76a0776ae74036e77cd11018083743453d7ad35 # v1.0.179
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           track_progress: true

{openretailscience-0.46.0 → openretailscience-0.48.0}/.github/workflows/claude.yml

@@ -27,7 +27,7 @@ jobs:
     steps:
       - name: Check user permissions
         id: check_permissions
-        uses: actions/github-script@v7
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             let actor;
@@ -60,7 +60,7 @@ jobs:
 
       - name: Comment on permission denied
         if: steps.check_permissions.outputs.has_permission == 'false'
-        uses: actions/github-script@v7
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             let issueNumber;
@@ -85,14 +85,15 @@ jobs:
 
       - name: Checkout repository
         if: steps.check_permissions.outputs.has_permission == 'true'
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 1
+          persist-credentials: false
 
       - name: Run Claude Code
         if: steps.check_permissions.outputs.has_permission == 'true'
         id: claude
-        uses: anthropics/claude-code-action@v1
+        uses: anthropics/claude-code-action@b76a0776ae74036e77cd11018083743453d7ad35 # v1.0.179
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 

{openretailscience-0.46.0 → openretailscience-0.48.0}/.github/workflows/cloudflare-docs-preview.yml

@@ -22,23 +22,25 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
-
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.11"
 
-      - name: Install uv Package
-        run: |
-          pip install --upgrade pip
-          pip install uv==0.5.30
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          # Disabled: a shared cache feeding the preview deploy is a poisoning vector.
+          enable-cache: "false"
 
       - name: Install Dependencies
-        run: uv sync
+        run: uv sync --locked
 
       - name: Build docs
-        run: uv run mkdocs build
+        run: uv run mkdocs build --strict
 
       - name: Verify build output
         run: |
@@ -50,18 +52,16 @@ jobs:
 
       - name: Publish to Cloudflare Pages
         id: cloudflare-deploy
-        uses: cloudflare/pages-action@v1
+        uses: cloudflare/wrangler-action@ebbaa1584979971c8614a24965b4405ff95890e0 # v4.0.0
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          projectName: openretailscience-docs
-          directory: site
           gitHubToken: ${{ secrets.GITHUB_TOKEN }}
-          branch: ${{ github.head_ref || github.ref_name }}
+          command: pages deploy site --project-name=openretailscience-docs --branch=${{ github.head_ref || github.ref_name }}
 
       - name: Find existing comment
         if: github.event_name == 'pull_request'
-        uses: peter-evans/find-comment@v3
+        uses: peter-evans/find-comment@b30e6a3c0ed37e7c023ccd3f1db5c6c0b0c23aad # v4.0.0
         id: find-comment
         with:
           issue-number: ${{ github.event.pull_request.number }}
@@ -70,7 +70,7 @@ jobs:
 
       - name: Create or update deployment comment
         if: github.event_name == 'pull_request'
-        uses: peter-evans/create-or-update-comment@v4
+        uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9 # v5.0.0
         with:
           comment-id: ${{ steps.find-comment.outputs.comment-id }}
           issue-number: ${{ github.event.pull_request.number }}
@@ -80,15 +80,15 @@ jobs:
 
             ✅ Preview deployed successfully!
 
-            **Preview URL:** ${{ steps.cloudflare-deploy.outputs.url }}
-            **Deployment ID:** ${{ steps.cloudflare-deploy.outputs.id }}
+            **Preview URL:** ${{ steps.cloudflare-deploy.outputs.deployment-url }}
+            **Deployment ID:** ${{ steps.cloudflare-deploy.outputs.pages-deployment-id }}
 
             ---
             *This preview will be updated automatically when you push new changes to this PR.*
 
       - name: Comment on deployment failure
         if: failure() && github.event_name == 'pull_request'
-        uses: actions/github-script@v7
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             github.rest.issues.createComment({

openretailscience-0.48.0/.github/workflows/gh-page.yml

@@ -0,0 +1,46 @@
+name: Page Deploy
+on:
+  workflow_call:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+jobs:
+  docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Setup Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+      - name: Install Dependencies
+        run: uv sync --locked
+      - name: Build docs
+        run: uv run mkdocs build
+      - name: Setup Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: "site/"
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

openretailscience-0.48.0/.github/workflows/oracle-integration.yml

@@ -0,0 +1,46 @@
+name: Oracle Integration Tests
+
+on:
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  integration-tests:
+    name: Run Oracle Integration Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Setup Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+
+      - name: Install Dependencies
+        run: |
+          uv sync --locked
+
+      # Oracle 23ai Free (the supported LTS); the Compose file pins the gvenzl image.
+      - name: Start Oracle
+        run: |
+          docker compose -f tests/integration/docker/docker-compose.oracle.yml up -d --wait --wait-timeout 600
+
+      - name: Run Integration Tests
+        run: |
+          uv run pytest tests/integration -k "oracle" -v
+
+      - name: Stop Oracle
+        if: always()
+        run: |
+          docker compose -f tests/integration/docker/docker-compose.oracle.yml down -v

openretailscience-0.48.0/.github/workflows/pyspark-integration.yml

@@ -0,0 +1,36 @@
+name: PySpark Integration Tests
+
+on:
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  integration-tests:
+    name: Run PySpark Integration Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Setup Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+
+      - name: Install Dependencies
+        run: |
+          uv sync --locked
+
+      - name: Run Integration Tests
+        run: |
+          uv run pytest tests/integration -k "pyspark" -v

openretailscience-0.48.0/.github/workflows/release.yml

@@ -0,0 +1,206 @@
+name: PyPi Package Deploy
+on:
+  workflow_dispatch:
+    inputs:
+      release:
+        type: choice
+        description: Select Release Type
+        default: "minor"
+        options:
+          - major
+          - minor
+          - patch
+permissions:
+  contents: read
+concurrency:
+  group: "release"
+  cancel-in-progress: false
+jobs:
+  pre-commit:
+    name: Pre-Commit Checks
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Setup Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --locked
+      - name: Run Pre-commit
+        run: uv run pre-commit run --all-files
+
+  security-audit:
+    name: Dependency Security Audit
+    uses: ./.github/workflows/security-audit.yml
+    permissions:
+      contents: read
+      security-events: write
+
+  bigquery-integration-tests:
+    name: BigQuery Integration Tests
+    uses: ./.github/workflows/bigquery-integration.yml
+    secrets:
+      GCP_SA_KEY: ${{ secrets.GCP_SA_KEY }}
+      GCP_PROJECT_ID: ${{ secrets.GCP_PROJECT_ID }}
+
+  pyspark-integration-tests:
+    name: PySpark Integration Tests
+    uses: ./.github/workflows/pyspark-integration.yml
+
+  snowflake-integration-tests:
+    name: Snowflake Integration Tests
+    uses: ./.github/workflows/snowflake-integration.yml
+    secrets:
+      GCP_SA_KEY: ${{ secrets.GCP_SA_KEY }}
+      GCP_INFRA_PROJECT_ID: ${{ secrets.GCP_INFRA_PROJECT_ID }}
+      SNOWFLAKE_CI_ACCOUNT: ${{ secrets.SNOWFLAKE_CI_ACCOUNT }}
+      SNOWFLAKE_CI_USER: ${{ secrets.SNOWFLAKE_CI_USER }}
+      SNOWFLAKE_CI_WAREHOUSE: ${{ secrets.SNOWFLAKE_CI_WAREHOUSE }}
+      SNOWFLAKE_CI_DATABASE: ${{ secrets.SNOWFLAKE_CI_DATABASE }}
+      SNOWFLAKE_CI_SCHEMA: ${{ secrets.SNOWFLAKE_CI_SCHEMA }}
+
+  sqlserver-integration-tests:
+    name: SQL Server Integration Tests
+    uses: ./.github/workflows/sqlserver-integration.yml
+
+  oracle-integration-tests:
+    name: Oracle Integration Tests
+    uses: ./.github/workflows/oracle-integration.yml
+
+  multi-python-tests:
+    name: Multi-Python Version Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: |
+          uv sync --locked
+      - name: Run tests (excluding integration)
+        run: |
+          uv run pytest tests/ --ignore=tests/integration --tb=short -v
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: [security-audit, pre-commit, bigquery-integration-tests, pyspark-integration-tests, snowflake-integration-tests, sqlserver-integration-tests, oracle-integration-tests, multi-python-tests]
+    permissions:
+      contents: write
+      id-token: write
+      attestations: write
+    env:
+      CI_COMMIT_MESSAGE: Continuous Integration Version Bump ${{ inputs.release }}
+    steps:
+      # zizmor: ignore[artipacked] this job pushes the version-bump commit and
+      # tag, so it requires the GITHUB_TOKEN persisted by actions/checkout. Only
+      # dist/ is uploaded as an artifact, not .git/, so the token is not exposed.
+      - name: Checkout # zizmor: ignore[artipacked]
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Setup Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+      - name: Install Dependencies
+        run: uv sync --locked --group dev
+      - name: Bump Version
+        run: |
+          uv run python - <<EOF
+          from tomlkit import parse, dumps
+          from tomlkit.toml_file import TOMLFile
+          file = TOMLFile("pyproject.toml")
+          doc = file.read()
+          version = doc["project"]["version"]
+          release = "${{ inputs.release }}"
+          major, minor, patch = map(int, version.split('.'))
+          if release == "major":
+              new_version = f"{major + 1}.0.0"
+          elif release == "minor":
+              new_version = f"{major}.{minor + 1}.0"
+          elif release == "patch":
+              new_version = f"{major}.{minor}.{patch + 1}"
+          doc["project"]["version"] = new_version
+          file.write(doc)
+          print(f"New Version: {new_version}")
+          EOF
+          echo "RELEASE_TAG=$(uv run python -c 'from tomlkit.toml_file import TOMLFile; print(TOMLFile("pyproject.toml").read()["project"]["version"])')" >> $GITHUB_ENV
+      - name: Build package
+        run: uv build
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
+        with:
+          subject-path: "dist/*"
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: build
+          path: dist/
+          retention-days: 1
+      - name: GIT commit and tag
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+          git add pyproject.toml
+          git commit -m "$CI_COMMIT_MESSAGE"
+          git push
+          echo "Tagging new version: $RELEASE_TAG"
+          git tag -a "$RELEASE_TAG" -m "Auto-generated tag"
+          git push origin "$RELEASE_TAG"
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release create "$RELEASE_TAG" --generate-notes
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    needs: build
+    environment:
+      name: production
+      url: "https://pypi.org/project/openretailscience"
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: build
+          path: dist
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
+        with:
+          attestations: true
+  deploy-docs:
+    name: Deploy Documentation
+    needs: pypi-publish
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    uses: ./.github/workflows/gh-page.yml

openretailscience-0.48.0/.github/workflows/security-audit.yml

@@ -0,0 +1,86 @@
+name: Security Audit
+
+# Scans the resolved dependency lockfile (uv.lock) for known vulnerabilities
+# using OSV-Scanner. Because it reads uv.lock statically, it audits every pinned
+# version across all supported Python versions (3.10-3.13) and platforms.
+# Results are uploaded to GitHub code scanning (Security tab) as SARIF, so a
+# newly-disclosed CVE in a pinned dependency surfaces as a failing check and a
+# code-scanning alert rather than a passive Dependabot alert.
+#
+# Suppressions (each with a rationale, and an ignoreUntil expiry where a fix may
+# yet appear) live in osv-scanner.toml at the repo root.
+#
+# On pull requests the scan runs only when dependencies or this workflow change,
+# and is advisory (results still post to code scanning); pushes to main (same
+# path filter) refresh the default-branch code-scanning state, and manual
+# dispatches and release calls are hard gates. Detection of newly-disclosed CVEs
+# against already-pinned dependencies (with no repo change) is left to Dependabot
+# alerts and security updates, so no scheduled scan is needed here.
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    paths:
+      - "uv.lock"
+      - "pyproject.toml"
+      - "osv-scanner.toml"
+      - ".github/workflows/security-audit.yml"
+  push:
+    branches: [main]
+    paths:
+      - "uv.lock"
+      - "pyproject.toml"
+      - "osv-scanner.toml"
+      - ".github/workflows/security-audit.yml"
+  workflow_dispatch:
+  workflow_call:
+
+permissions: {}
+
+concurrency:
+  group: "security-audit-${{ github.ref }}-${{ github.event_name }}"
+  cancel-in-progress: true
+
+jobs:
+  osv-scan:
+    name: OSV-Scanner (uv.lock)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      security-events: write # upload SARIF to code scanning
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Run OSV-Scanner
+        id: osv
+        continue-on-error: true # gate is enforced explicitly below, after SARIF upload
+        uses: google/osv-scanner-action/osv-scanner-action@9a498708959aeaef5ef730655706c5a1df1edbc2 # v2.3.8
+        with:
+          scan-args: |-
+            --config=osv-scanner.toml
+            --format=sarif
+            --output=results.sarif
+            --lockfile=uv.lock
+      - name: Upload results to code scanning
+        # Skip cleanly if the scanner errored before writing the SARIF, rather
+        # than erroring and being swallowed by continue-on-error.
+        if: always() && hashFiles('results.sarif') != ''
+        continue-on-error: true # never let SARIF upload (e.g. missing perms) break the gate
+        uses: github/codeql-action/upload-sarif@7188fc363630916deb702c7fdcf4e481b751f97a # v4.37.1
+        with:
+          sarif_file: results.sarif
+          category: osv-scanner
+      - name: Enforce gate
+        # Pull requests are advisory only (results still post to code scanning);
+        # every other trigger is a hard gate. Fail closed: block unless the scan
+        # completed successfully, so a failed, errored, or skipped scan never
+        # passes the gate. !cancelled() (rather than always()) avoids marking a
+        # concurrency-superseded run as failed; a real timeout still blocks
+        # downstream via the job's needs dependency.
+        if: ${{ !cancelled() && github.event_name != 'pull_request' && steps.osv.outcome != 'success' }}
+        run: |
+          echo "::error::OSV-Scanner did not complete cleanly (vulnerabilities found or scan failed) — see the SARIF results in the Security tab."
+          exit 1