feat(packaging): rebuild OpenTelemetry observability extra on current main

.github/workflows/materialize-opentelemetry-lock.yml

@@ -0,0 +1,94 @@
+name: Materialize OpenTelemetry Lock Evidence
+
+on:
+  push:
+    branches:
+      - feat/opentelemetry-observability-extra-current-main
+    paths:
+      - .github/workflows/materialize-opentelemetry-lock.yml
+      - pyproject.toml
+      - tests/test_opentelemetry_optional_dependency.py
+
+permissions:
+  contents: read
+
+concurrency:
+  group: materialize-opentelemetry-lock
+  cancel-in-progress: true
+
+jobs:
+  materialize:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Harden runner
+        uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
+        with:
+          egress-policy: audit
+
+      - name: Check out exact branch head
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+
+      - name: Verify exact source
+        shell: bash
+        run: test "$(git rev-parse HEAD)" = "${{ github.sha }}"
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+
+      - name: Set up repository-pinned uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.12.3"
+          prune-cache: true
+
+      - name: Resolve and verify the exact lock graph
+        shell: bash
+        run: |
+          set -euo pipefail
+          uv lock
+          uv lock --check
+          uv sync --locked --extra observability
+          uv run pytest -q tests/test_opentelemetry_optional_dependency.py tests/test_opentelemetry_operations.py
+          uv build --no-sources
+
+      - name: Verify clean base and observability installations
+        shell: bash
+        run: |
+          set -euo pipefail
+          wheel="$(find dist -maxdepth 1 -type f -name '*.whl' -print -quit)"
+          test -n "$wheel"
+
+          python -m venv /tmp/pg-llm-batch-base
+          /tmp/pg-llm-batch-base/bin/python -m pip install --disable-pip-version-check "$wheel"
+          /tmp/pg-llm-batch-base/bin/python - <<'PY'
+          import importlib.util
+          import pg_llm_batch
+
+          assert pg_llm_batch is not None
+          assert importlib.util.find_spec("opentelemetry") is None
+          PY
+
+          python -m venv /tmp/pg-llm-batch-observability
+          /tmp/pg-llm-batch-observability/bin/python -m pip install --disable-pip-version-check "${wheel}[observability]"
+          /tmp/pg-llm-batch-observability/bin/python - <<'PY'
+          import importlib.util
+
+          from pg_llm_batch.opentelemetry_client import OpenTelemetryBatchAPIClient
+
+          assert importlib.util.find_spec("opentelemetry") is not None
+          assert OpenTelemetryBatchAPIClient.from_global_provider is not None
+          PY
+
+      - name: Upload reviewed lock evidence
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: opentelemetry-lock-${{ github.sha }}
+          path: uv.lock
+          if-no-files-found: error
+          retention-days: 3

pyproject.toml

@@ -18,6 +18,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+observability = ["opentelemetry-api>=1.44,<2"]
 secrets = ["cryptography>=50.0.0"]
 test = [
     "pytest>=7.4",

tests/test_opentelemetry_optional_dependency.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Contract tests for the first-class OpenTelemetry optional dependency."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python 3.10
+    import tomli as tomllib
+
+
+ROOT = Path(__file__).resolve().parents[1]
+OBSERVABILITY_API_REQUIREMENT = "opentelemetry-api>=1.44,<2"
+
+
+def _project_metadata() -> dict[str, object]:
+    """Load the package metadata used by build and installation tooling."""
+    return tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))[
+        "project"
+    ]
+
+
+def test_observability_extra_declares_api_only_dependency() -> None:
+    """Package metadata exposes bounded API-only OpenTelemetry installation."""
+    project = _project_metadata()
+    extras = project["optional-dependencies"]
+
+    assert extras["observability"] == [OBSERVABILITY_API_REQUIREMENT]
+    assert not any(
+        requirement.startswith("opentelemetry-sdk")
+        for requirement in extras["observability"]
+    )
+
+
+def test_base_runtime_remains_opentelemetry_independent() -> None:
+    """The default install must not silently acquire telemetry dependencies."""
+    project = _project_metadata()
+    dependencies = project["dependencies"]
+
+    assert not any(
+        requirement.startswith("opentelemetry-") for requirement in dependencies
+    )
+
+
+def test_observability_extra_has_one_explicit_runtime_requirement() -> None:
+    """Keep the optional installation surface minimal and reviewable."""
+    project = _project_metadata()
+    extras = project["optional-dependencies"]
+
+    assert set(extras) >= {"observability", "secrets", "test"}
+    assert len(extras["observability"]) == 1