provenance-telemetry 0.1.0__tar.gz

provenance_telemetry-0.1.0/.github/workflows/build-package.yml

@@ -0,0 +1,106 @@
+name: Build Python Package
+
+# Builds the provenance-telemetry sdist+wheel on every push and PR so consumers
+# can grab the latest from a workflow artifact. On tag pushes (vX.Y.Z) the
+# artifacts are attached to a GitHub Release AND published to PyPI (trusted
+# publishing — OIDC, no API token stored anywhere).
+#
+# Distribution name and import package agree: `pip install provenance-telemetry`
+# -> `import provenance_telemetry`.
+#
+#   pip install provenance-telemetry
+#   # or pin directly from git, to a TAG and never a branch:
+#   uv add "provenance-telemetry @ git+https://github.com/edgy-solutions/provenance-telemetry.git@v0.1.0"
+#
+# ONE-TIME SETUP for the publish job (it cannot work until this is done):
+#   1. On PyPI: Account -> Publishing -> add a GitHub trusted publisher with
+#      owner `edgy-solutions`, repo `provenance-telemetry`,
+#      workflow `build-package.yml`, environment `pypi`.
+#   2. In this repo: Settings -> Environments -> create `pypi`.
+# Until step 1 exists the tag build still succeeds and the Release is still
+# created; only the publish job fails, and it fails LOUDLY rather than silently
+# skipping — a release that quietly did not publish is the worst outcome here.
+
+on:
+  push:
+    branches: [master, main]
+    tags: ['v*']
+  pull_request:
+    branches: [master, main]
+  workflow_dispatch:
+
+permissions:
+  contents: write   # needed to publish the wheel as a release asset on tag pushes
+
+jobs:
+  build:
+    name: Build wheel
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build wheel + sdist
+        run: uv build          # both sdist + wheel (PyPI wants both)
+
+      # The tag and the packaged version must agree. Publishing v0.1.1 from a
+      # tree whose pyproject still says 0.1.0 yields an immutable PyPI release
+      # under the wrong number that can never be corrected, only yanked.
+      - name: Assert the tag matches the packaged version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          VER=$(ls dist/*.tar.gz | sed -E 's/.*-([0-9][^-]*)\.tar\.gz/\1/')
+          echo "tag=$TAG packaged=$VER"
+          test "$TAG" = "$VER" || {
+            echo "::error::tag v$TAG does not match packaged version $VER —"
+            echo "::error::bump the version field in pyproject.toml, or retag."
+            exit 1
+          }
+
+      # A wheel that imports on the build machine but not from the artifact is
+      # the packaging equivalent of a passing suite over a broken image. Install
+      # the built wheel into a clean venv and import it.
+      - name: Smoke-test the built wheel in a clean venv
+        run: |
+          uv venv --python 3.12 /tmp/smoke
+          VIRTUAL_ENV=/tmp/smoke uv pip install dist/*.whl
+          /tmp/smoke/bin/python -c "import provenance_telemetry as pt; print('ok', sorted(pt.__all__))"
+
+      - name: Upload as workflow artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: provenance-telemetry-dist
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 30
+
+      - name: Attach to GitHub Release (on tag)
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true
+          fail_on_unmatched_files: true
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    # Only publish on a version tag push (e.g. v0.1.0), never on branch/PR builds.
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC token for PyPI Trusted Publishing — no API token/secret needed
+    steps:
+      - name: Download built distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: provenance-telemetry-dist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

provenance_telemetry-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,105 @@
+name: Tests
+
+# Runs the suite on every push and PR, across the FULL supported Python range.
+#
+# The matrix is the point, not decoration. Before this workflow existed the
+# package declared `requires-python = ">=3.9"` while two of its four dependencies
+# (langfuse and opentelemetry-api) refuse anything below 3.10 — so the floor was
+# not merely untested, it was FALSE, and the failure it produced would have named
+# langfuse rather than this package. A support range nothing exercises is a claim;
+# running the floor and the ceiling turns it into a measurement.
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+  workflow_dispatch:
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: py${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Floor and ceiling of `requires-python = ">=3.10,<3.15"`, plus the
+        # versions in between. If a future dependency bump raises the real floor,
+        # the 3.10 leg fails HERE rather than in an adopter's install.
+        python: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Create venv
+        run: uv venv --python ${{ matrix.python }}
+
+      - name: Install package + dev extra
+        run: uv pip install -e ".[dev]"
+
+      - name: Show resolved versions
+        run: uv pip list | grep -Ei "^(langfuse|opentelemetry|pydantic|PyYAML|pytest)" || true
+
+      # The suite must run with Langfuse DISABLED. Every entry point in this
+      # package gates on LANGFUSE_SECRET_KEY + LANGFUSE_PUBLIC_KEY being present,
+      # so a runner that happened to carry real credentials would take entirely
+      # different code paths AND emit test spans into a real project. Unset
+      # explicitly rather than trusting the runner to be clean.
+      - name: Run tests (telemetry disabled)
+        env:
+          LANGFUSE_SECRET_KEY: ""
+          LANGFUSE_PUBLIC_KEY: ""
+          LANGFUSE_HOST: ""
+        run: |
+          set -o pipefail
+          .venv/bin/python -m pytest tests -q --no-header -rs \
+            --junitxml=junit-${{ matrix.python }}.xml 2>&1 | tee pytest-output.txt
+
+      # A skipped test is indistinguishable from a passing one in a summary line.
+      # This package's suite is designed to run without credentials, so a skip
+      # citing a missing import means CI is under-installed — the coverage
+      # quietly shrank and the job still went green.
+      - name: Fail on dependency-driven skips
+        if: always()
+        run: |
+          if grep -E "SKIPPED.*(could not import|not installed|No module named)" pytest-output.txt; then
+            echo "::error::Tests skipped because a dependency is missing. CI is under-installed —"
+            echo "::error::add the package so these tests actually run instead of silently passing."
+            exit 1
+          fi
+          echo "No dependency-driven skips."
+
+      # The public surface is the contract. An export that disappears is a
+      # breaking change for every adopter, and nothing else in the suite would
+      # notice — the README documents exactly these names.
+      - name: Assert the documented public surface still exists
+        run: |
+          .venv/bin/python - <<'PY'
+          import provenance_telemetry as pt
+          documented = {"Mapping","ScoreSpec","load_mapping","KNOWN_SLOTS",
+                        "KNOWN_SCORE_ENCODINGS","set_trace_standard","observed_trace",
+                        "emit_misses","span_descriptor","litellm_metadata",
+                        "observe_span","traced","redact"}
+          missing = sorted(n for n in documented if not hasattr(pt, n))
+          assert not missing, f"public surface lost: {missing}"
+          extra = sorted(set(pt.__all__) - documented)
+          assert not extra, f"exported but undocumented in README: {extra}"
+          print(f"public surface intact ({len(documented)} names)")
+          PY
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: junit-py${{ matrix.python }}
+          path: junit-${{ matrix.python }}.xml
+          if-no-files-found: warn
+          retention-days: 14

provenance_telemetry-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/

provenance_telemetry-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edgy Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

provenance_telemetry-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: provenance-telemetry
+Version: 0.1.0
+Summary: Project an existing provenance doctrine into an observability backend. Vocabulary is config, not code.
+Project-URL: Homepage, https://github.com/edgy-solutions/provenance-telemetry
+Project-URL: Repository, https://github.com/edgy-solutions/provenance-telemetry
+Project-URL: Issues, https://github.com/edgy-solutions/provenance-telemetry/issues
+Author-email: Chris Nogradi <cnogradi@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: langfuse,llm,observability,opentelemetry,provenance,telemetry,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Requires-Python: <3.15,>=3.10
+Requires-Dist: langfuse>=3.0.0
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# provenance-telemetry
+
+**Telemetry is your provenance doctrine projected into an observability backend:** trace identity from artifact keys (never LLM-derived), user/session from your identity key, span attributes and scores from the fields your system of record already uses — so a trace and a decision record tell the same story *in the same words*, and adopters inherit the **vocabulary, not just the plumbing**.
+
+**The dependency list *is* the adoption pitch.** Four dependencies — `langfuse`, `opentelemetry-api`, `pydantic`, `pyyaml` — one doctrine, config-governed vocabulary. This library ships **no vocabulary of its own**: which of *your* provenance fields map onto which Langfuse slot is a small ratifiable mapping config *you* supply. That is what lets any team adopt it without importing anyone else's domain — and what keeps a security review's read of this `README` + `pyproject` short.
+
+---
+
+## Install
+
+```toml
+# pyproject.toml — from PyPI (preferred)
+dependencies = ["provenance-telemetry>=0.1.0,<0.2"]
+```
+
+```toml
+# pyproject.toml — direct from git, pinned to a TAG (pre-index form)
+dependencies = [
+  "provenance-telemetry @ git+https://github.com/edgy-solutions/provenance-telemetry.git@v0.1.0",
+]
+```
+
+> **Never a floating ref.** A `git+https://…` with no `@ref` resolves to the default branch **at build time**, so a single upstream commit changes what every consuming service ships — with nobody deciding, and no diff in the consumer's repo to review. This is not hypothetical: a sibling package renamed its *distribution* on `master`, and every consumer floating on that branch broke on the next clean resolve, while machines holding a stale install kept working so the repo looked healthy. Pin to a tag, or to a version once it is on an index.
+
+> **The distribution name is `provenance-telemetry`; the import name is `provenance_telemetry`.** These are different namespaces and they are allowed to diverge — which is exactly how the failure above happened, because a rename of one is invisible to code that only ever types the other. **The import name is the load-bearing one and will not change without a major version.** If the distribution is ever renamed, `import provenance_telemetry` keeps working and only your dependency *declaration* needs editing.
+
+## Enabling it
+
+Everything in this library is **inert unless both** of these are set:
+
+```bash
+LANGFUSE_PUBLIC_KEY=pk-...
+LANGFUSE_SECRET_KEY=sk-...
+LANGFUSE_HOST=https://langfuse.example.com   # read by the langfuse SDK itself
+```
+
+With either missing, every entry point becomes a pass-through: context managers yield, decorators return the undecorated function, emitters return without emitting. **No-credentials code carries no runtime dependency on Langfuse being reachable.**
+
+> ⚠️ **`traced` gates at DECORATION time**, i.e. at module import. If you set the environment *after* importing the module that uses `@traced`, the decorator has already resolved to pass-through. This matches the deployment model (env set before the process starts) but bites in notebooks and tests. `observed_trace`, `observe_span` and `set_trace_standard` gate at **call** time and do not have this constraint.
+
+---
+
+## Quickstart — a traced service entry
+
+The shape used across a real ten-engine mesh: join the caller's trace on an inbound header, enrich it from your provenance values, and let everything inside nest automatically.
+
+```python
+from fastapi import FastAPI, Request
+from provenance_telemetry import load_mapping, observed_trace, observe_span
+
+MAPPING = load_mapping("config/mesh-mapping.yaml")   # shape-validated at load
+app = FastAPI()
+
+@app.post("/analyze")
+async def analyze(req: Request, body: dict):
+    values = {
+        "request_key": req.headers.get("X-Trace-Id"),  # -> trace_id slot: THE JOIN
+        "authz_id":    req.headers.get("X-Authz-Id"),  # -> user_id slot
+        "session_id":  body.get("session_id"),
+        "engine":      "analyst",
+        "verb":        "analyzeWithCodeAgent",
+        "domain":      body.get("domain"),
+    }
+    with observed_trace(MAPPING, values, name="analyze"):
+        with observe_span("plan", verb=values["verb"]):
+            plan = build_plan(body)
+        return run(plan)
+```
+
+**What makes this a join and not a new trace:** `observed_trace` reads the field your mapping puts in the `trace_id` slot (`request_key` above) and derives a deterministic Langfuse id from it via `create_trace_id(seed=...)`. Two services handed the **same** `X-Trace-Id` compute the **same** Langfuse trace id, so their spans land on **one** trace. The join is native, not a reconciliation step.
+
+If the seed field is absent, `observed_trace` opens a fresh trace instead — which is correct, but means **a caller that forgets the header silently gets an orphan trace rather than an error.** If joins are load-bearing for you, assert the header's presence in your own code; this library will not refuse the work to protect the telemetry.
+
+### Propagating the trace to the next hop
+
+The join only holds if the id travels. Send it on every outbound call:
+
+```python
+headers = {"X-Trace-Id": values["request_key"], "X-Authz-Id": values["authz_id"]}
+httpx.post(next_engine_url, json=payload, headers=headers)
+```
+
+---
+
+## API
+
+### `load_mapping(source) -> Mapping`
+
+Accepts a path or a dict. **Shape-validated at load**: an unknown Langfuse slot or score encoding raises `pydantic.ValidationError` immediately.
+
+Two-tier validation is deliberate. This library validates **shape** — `KNOWN_SLOTS` (`trace_id`, `user_id`, `session_id`, `release`, `version`) and `KNOWN_SCORE_ENCODINGS` (`ordinal`, `fraction`, `binary_per_join`, `count_total`) are closed sets. It does **not** validate that the provenance field names on the right-hand side exist — that is **truth**, and it belongs with whoever owns the vocabulary. Add a CI check in *your* repo asserting your mapping's field names exist in your contracts; that is the half this library cannot do for you, and skipping it is how a mapping quietly projects `None` forever.
+
+### `observed_trace(mapping, values, *, name="operation", as_type="span")`
+
+Context manager. **The entry primitive** — opens or *joins* a trace on the mapped `trace_id`, then enriches it. Everything opened inside nests under it via the ordinary OTel context.
+
+### `set_trace_standard(mapping, values)`
+
+Enrich the **current** trace in place: identity slots, tags, metadata as OTel attributes, plus scores. Use when something you learned *later* in the request belongs on the trace.
+
+**It cannot set the trace id** — under Langfuse v4 a trace's id is fixed at creation. Choose the id at the entry with `observed_trace`. Calling this with a `trace_id` slot mapped is not an error; the slot is simply skipped.
+
+### `observe_span(operation, **attributes)` / `litellm_metadata(operation, ...)`
+
+Two carriers for **one** span shape (both derive from `span_descriptor`), so a direct-provider call and a LiteLLM-proxied call emit comparable spans:
+
+```python
+# direct provider — explicit span; a generation created inside nests automatically
+with observe_span("classify", model="gpt-oss", domain=domain) as d:
+    result = client.chat.completions.create(...)
+
+# through a LiteLLM proxy — feed the callback metadata instead
+import litellm
+litellm.completion(model="gpt-4o-mini", messages=msgs,
+                   metadata=litellm_metadata("classify", trace_id=tid, user_id=uid,
+                                             session_id=sid, tags=["analyst"], domain=domain))
+```
+
+### `traced(name=None, as_type=None)`
+
+Decorator that opens a span/trace around a function. For a top-level entry that must open on a **chosen** id, use `observed_trace` — `traced` wraps Langfuse's `observe`, which mints its own id and therefore **cannot join**. See the decoration-time gating warning above.
+
+### `redact(value) -> str`
+
+**Hash, don't drop.** Returns `sha1:<16 hex>`. A redacted trace stays *joinable* — two traces referencing the same value still collide on the hash — without carrying the content. Applied automatically to any field listed in `content_bearing`; call it directly for ad-hoc values.
+
+`is_redacted(value)` also exists but is **not** exported at top level in this release — import it as `from provenance_telemetry.redact import is_redacted`.
+
+### `emit_misses() -> int`
+
+**Fail-soft is only honest if it is countable.** Every soft failure — SDK absent, Langfuse unreachable, a bad score, an enrichment error — increments this counter and logs a warning; nothing raises. Telemetry must not stop the work it observes, but *silent* telemetry loss is indistinguishable from a healthy quiet system. Export it:
+
+```python
+@app.get("/health")
+def health():
+    return {"status": "ok", "telemetry_misses": emit_misses()}
+```
+
+A rising count means you are flying blind and do not know it. Alert on the **derivative**, not the value.
+
+---
+
+## The mapping config (you supply this)
+
+```yaml
+version: 1
+slots:                       # langfuse slot  ->  your provenance field
+  trace_id:  request_key
+  user_id:   authz_id
+  session_id: session_id
+tags:        [engine, verb, domain]
+metadata:    [subject_class, resolved_via, chart_version]
+scores:                      # honest-degradation signals, projected from your schema
+  confidence_tier: {encoding: ordinal}
+  needs_review:    {encoding: fraction}
+  coherence:       {encoding: binary_per_join}
+  crops_failed:    {encoding: count_total}
+content_bearing: [mpn, notice_id, snippet, matched_text, override_reason]
+```
+
+The field *names* on the right are yours. This library never names them in its source (a deletion seal enforces it) — they live only in your mapping, checked for truth by you. See [`examples/mesh-mapping.example.yaml`](examples/mesh-mapping.example.yaml).
+
+---
+
+## Recipes
+
+- **[Durable execution (Restate, Temporal, any replaying runtime)](docs/durable-execution.md)** — the entry primitive is **not** replay-safe on its own, and the failure is invisible in a green test suite. Read this before instrumenting a durable handler.
+
+## Non-goals
+
+- **It will not refuse your work.** Every failure path is soft. If a trace *must* exist for compliance, that is a check you own; this library is a witness channel, not a gate.
+- **It does not own your vocabulary.** No provenance field name appears in this source, by design and by test.
+- **It does not verify your mapping is true** — only that it is well-shaped. See the two-tier split above.

provenance_telemetry-0.1.0/README.md

@@ -0,0 +1,173 @@
+# provenance-telemetry
+
+**Telemetry is your provenance doctrine projected into an observability backend:** trace identity from artifact keys (never LLM-derived), user/session from your identity key, span attributes and scores from the fields your system of record already uses — so a trace and a decision record tell the same story *in the same words*, and adopters inherit the **vocabulary, not just the plumbing**.
+
+**The dependency list *is* the adoption pitch.** Four dependencies — `langfuse`, `opentelemetry-api`, `pydantic`, `pyyaml` — one doctrine, config-governed vocabulary. This library ships **no vocabulary of its own**: which of *your* provenance fields map onto which Langfuse slot is a small ratifiable mapping config *you* supply. That is what lets any team adopt it without importing anyone else's domain — and what keeps a security review's read of this `README` + `pyproject` short.
+
+---
+
+## Install
+
+```toml
+# pyproject.toml — from PyPI (preferred)
+dependencies = ["provenance-telemetry>=0.1.0,<0.2"]
+```
+
+```toml
+# pyproject.toml — direct from git, pinned to a TAG (pre-index form)
+dependencies = [
+  "provenance-telemetry @ git+https://github.com/edgy-solutions/provenance-telemetry.git@v0.1.0",
+]
+```
+
+> **Never a floating ref.** A `git+https://…` with no `@ref` resolves to the default branch **at build time**, so a single upstream commit changes what every consuming service ships — with nobody deciding, and no diff in the consumer's repo to review. This is not hypothetical: a sibling package renamed its *distribution* on `master`, and every consumer floating on that branch broke on the next clean resolve, while machines holding a stale install kept working so the repo looked healthy. Pin to a tag, or to a version once it is on an index.
+
+> **The distribution name is `provenance-telemetry`; the import name is `provenance_telemetry`.** These are different namespaces and they are allowed to diverge — which is exactly how the failure above happened, because a rename of one is invisible to code that only ever types the other. **The import name is the load-bearing one and will not change without a major version.** If the distribution is ever renamed, `import provenance_telemetry` keeps working and only your dependency *declaration* needs editing.
+
+## Enabling it
+
+Everything in this library is **inert unless both** of these are set:
+
+```bash
+LANGFUSE_PUBLIC_KEY=pk-...
+LANGFUSE_SECRET_KEY=sk-...
+LANGFUSE_HOST=https://langfuse.example.com   # read by the langfuse SDK itself
+```
+
+With either missing, every entry point becomes a pass-through: context managers yield, decorators return the undecorated function, emitters return without emitting. **No-credentials code carries no runtime dependency on Langfuse being reachable.**
+
+> ⚠️ **`traced` gates at DECORATION time**, i.e. at module import. If you set the environment *after* importing the module that uses `@traced`, the decorator has already resolved to pass-through. This matches the deployment model (env set before the process starts) but bites in notebooks and tests. `observed_trace`, `observe_span` and `set_trace_standard` gate at **call** time and do not have this constraint.
+
+---
+
+## Quickstart — a traced service entry
+
+The shape used across a real ten-engine mesh: join the caller's trace on an inbound header, enrich it from your provenance values, and let everything inside nest automatically.
+
+```python
+from fastapi import FastAPI, Request
+from provenance_telemetry import load_mapping, observed_trace, observe_span
+
+MAPPING = load_mapping("config/mesh-mapping.yaml")   # shape-validated at load
+app = FastAPI()
+
+@app.post("/analyze")
+async def analyze(req: Request, body: dict):
+    values = {
+        "request_key": req.headers.get("X-Trace-Id"),  # -> trace_id slot: THE JOIN
+        "authz_id":    req.headers.get("X-Authz-Id"),  # -> user_id slot
+        "session_id":  body.get("session_id"),
+        "engine":      "analyst",
+        "verb":        "analyzeWithCodeAgent",
+        "domain":      body.get("domain"),
+    }
+    with observed_trace(MAPPING, values, name="analyze"):
+        with observe_span("plan", verb=values["verb"]):
+            plan = build_plan(body)
+        return run(plan)
+```
+
+**What makes this a join and not a new trace:** `observed_trace` reads the field your mapping puts in the `trace_id` slot (`request_key` above) and derives a deterministic Langfuse id from it via `create_trace_id(seed=...)`. Two services handed the **same** `X-Trace-Id` compute the **same** Langfuse trace id, so their spans land on **one** trace. The join is native, not a reconciliation step.
+
+If the seed field is absent, `observed_trace` opens a fresh trace instead — which is correct, but means **a caller that forgets the header silently gets an orphan trace rather than an error.** If joins are load-bearing for you, assert the header's presence in your own code; this library will not refuse the work to protect the telemetry.
+
+### Propagating the trace to the next hop
+
+The join only holds if the id travels. Send it on every outbound call:
+
+```python
+headers = {"X-Trace-Id": values["request_key"], "X-Authz-Id": values["authz_id"]}
+httpx.post(next_engine_url, json=payload, headers=headers)
+```
+
+---
+
+## API
+
+### `load_mapping(source) -> Mapping`
+
+Accepts a path or a dict. **Shape-validated at load**: an unknown Langfuse slot or score encoding raises `pydantic.ValidationError` immediately.
+
+Two-tier validation is deliberate. This library validates **shape** — `KNOWN_SLOTS` (`trace_id`, `user_id`, `session_id`, `release`, `version`) and `KNOWN_SCORE_ENCODINGS` (`ordinal`, `fraction`, `binary_per_join`, `count_total`) are closed sets. It does **not** validate that the provenance field names on the right-hand side exist — that is **truth**, and it belongs with whoever owns the vocabulary. Add a CI check in *your* repo asserting your mapping's field names exist in your contracts; that is the half this library cannot do for you, and skipping it is how a mapping quietly projects `None` forever.
+
+### `observed_trace(mapping, values, *, name="operation", as_type="span")`
+
+Context manager. **The entry primitive** — opens or *joins* a trace on the mapped `trace_id`, then enriches it. Everything opened inside nests under it via the ordinary OTel context.
+
+### `set_trace_standard(mapping, values)`
+
+Enrich the **current** trace in place: identity slots, tags, metadata as OTel attributes, plus scores. Use when something you learned *later* in the request belongs on the trace.
+
+**It cannot set the trace id** — under Langfuse v4 a trace's id is fixed at creation. Choose the id at the entry with `observed_trace`. Calling this with a `trace_id` slot mapped is not an error; the slot is simply skipped.
+
+### `observe_span(operation, **attributes)` / `litellm_metadata(operation, ...)`
+
+Two carriers for **one** span shape (both derive from `span_descriptor`), so a direct-provider call and a LiteLLM-proxied call emit comparable spans:
+
+```python
+# direct provider — explicit span; a generation created inside nests automatically
+with observe_span("classify", model="gpt-oss", domain=domain) as d:
+    result = client.chat.completions.create(...)
+
+# through a LiteLLM proxy — feed the callback metadata instead
+import litellm
+litellm.completion(model="gpt-4o-mini", messages=msgs,
+                   metadata=litellm_metadata("classify", trace_id=tid, user_id=uid,
+                                             session_id=sid, tags=["analyst"], domain=domain))
+```
+
+### `traced(name=None, as_type=None)`
+
+Decorator that opens a span/trace around a function. For a top-level entry that must open on a **chosen** id, use `observed_trace` — `traced` wraps Langfuse's `observe`, which mints its own id and therefore **cannot join**. See the decoration-time gating warning above.
+
+### `redact(value) -> str`
+
+**Hash, don't drop.** Returns `sha1:<16 hex>`. A redacted trace stays *joinable* — two traces referencing the same value still collide on the hash — without carrying the content. Applied automatically to any field listed in `content_bearing`; call it directly for ad-hoc values.
+
+`is_redacted(value)` also exists but is **not** exported at top level in this release — import it as `from provenance_telemetry.redact import is_redacted`.
+
+### `emit_misses() -> int`
+
+**Fail-soft is only honest if it is countable.** Every soft failure — SDK absent, Langfuse unreachable, a bad score, an enrichment error — increments this counter and logs a warning; nothing raises. Telemetry must not stop the work it observes, but *silent* telemetry loss is indistinguishable from a healthy quiet system. Export it:
+
+```python
+@app.get("/health")
+def health():
+    return {"status": "ok", "telemetry_misses": emit_misses()}
+```
+
+A rising count means you are flying blind and do not know it. Alert on the **derivative**, not the value.
+
+---
+
+## The mapping config (you supply this)
+
+```yaml
+version: 1
+slots:                       # langfuse slot  ->  your provenance field
+  trace_id:  request_key
+  user_id:   authz_id
+  session_id: session_id
+tags:        [engine, verb, domain]
+metadata:    [subject_class, resolved_via, chart_version]
+scores:                      # honest-degradation signals, projected from your schema
+  confidence_tier: {encoding: ordinal}
+  needs_review:    {encoding: fraction}
+  coherence:       {encoding: binary_per_join}
+  crops_failed:    {encoding: count_total}
+content_bearing: [mpn, notice_id, snippet, matched_text, override_reason]
+```
+
+The field *names* on the right are yours. This library never names them in its source (a deletion seal enforces it) — they live only in your mapping, checked for truth by you. See [`examples/mesh-mapping.example.yaml`](examples/mesh-mapping.example.yaml).
+
+---
+
+## Recipes
+
+- **[Durable execution (Restate, Temporal, any replaying runtime)](docs/durable-execution.md)** — the entry primitive is **not** replay-safe on its own, and the failure is invisible in a green test suite. Read this before instrumenting a durable handler.
+
+## Non-goals
+
+- **It will not refuse your work.** Every failure path is soft. If a trace *must* exist for compliance, that is a check you own; this library is a witness channel, not a gate.
+- **It does not own your vocabulary.** No provenance field name appears in this source, by design and by test.
+- **It does not verify your mapping is true** — only that it is well-shaped. See the two-tier split above.