codex-pdf 1.7.2__tar.gz → 1.8.0__tar.gz

{codex_pdf-1.7.2 → codex_pdf-1.8.0}/CLAUDE.md

@@ -25,7 +25,7 @@ For new products (Forge, Trap, Impose, Marks, etc.), map capabilities to one own
 
 When work spans layers, define a contract seam and keep logic in its owner service.
 
-## Deployed surface (1.7.2)
+## Deployed surface (1.8.0)
 
 Codex now runs as **three services** in production. They share the
 same content-addressed cache key format

{codex_pdf-1.7.2 → codex_pdf-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-pdf
-Version: 1.7.2
+Version: 1.8.0
 Summary: Authoritative, versioned PDF facts contract for Think Neverland tools.
 Author-email: Think Neverland <dev@thinkneverland.com>
 License-Expression: AGPL-3.0-or-later
@@ -19,6 +19,8 @@ Provides-Extra: geom
 Requires-Dist: pyclipr>=0.1.8; extra == 'geom'
 Provides-Extra: redis
 Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: retain
+Requires-Dist: boto3>=1.34; extra == 'retain'
 Description-Content-Type: text/markdown
 
 ---

{codex_pdf-1.7.2 → codex_pdf-1.8.0}/clients/ts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@printwithsynergy/codex-client",
-  "version": "1.7.2",
+  "version": "1.8.0",
   "description": "TypeScript client for the codex-pdf HTTP API. Mirrors the Python codex_pdf.client surface.",
   "type": "module",
   "license": "AGPL-3.0-or-later",

{codex_pdf-1.7.2 → codex_pdf-1.8.0}/codex-edge/README.md

@@ -10,7 +10,7 @@ the Railway codex-pdf service.
 - **Account**: `99aa3f9229469650a746a7d39ac58448` (`Quincy@thinkneverland.com's Account`)
 - **KV namespace `CACHE`**: `89a21ce1937046018a3d9d38f4e763ff` (preview `a4856d6f3b244087b907c189c2a2277d`)
 - **Origin** (`CODEX_ORIGIN_URL`): `https://codex-pdf-lint-sidecar-production.up.railway.app`
-- **Codex version pinned**: `1.7.2` (`CODEX_VERSION` var — bump on origin release)
+- **Codex version pinned**: `1.8.0` (`CODEX_VERSION` var — bump on origin release)
 - **TTLs**: probe 24 h, Phase 1 24 h, Phase 2 7 d
 
 ## What it caches

{codex_pdf-1.7.2 → codex_pdf-1.8.0}/codex-edge/wrangler.toml

@@ -23,7 +23,7 @@ CODEX_ORIGIN_URL = "https://codex-pdf-lint-sidecar-production.up.railway.app"
 # Codex package VERSION at deploy time. MUST match the origin's
 # `codex_pdf.version.VERSION` so KV keys line up. Bump on every
 # origin release.
-CODEX_VERSION = "1.7.2"
+CODEX_VERSION = "1.8.0"
 # TTL (seconds) for cached SSE event payloads.
 PROBE_TTL = "86400"     # 24 h — small payload, refresh daily
 PHASE1_TTL = "86400"    # 24 h — matches origin Redis TTL

{codex_pdf-1.7.2 → codex_pdf-1.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codex-pdf"
-version = "1.7.2"
+version = "1.8.0"
 description = "Authoritative, versioned PDF facts contract for Think Neverland tools."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -29,6 +29,9 @@ redis = [
 geom = [
     "pyclipr>=0.1.8",
 ]
+retain = [
+    "boto3>=1.34",
+]
 
 [project.scripts]
 codex-pdf = "codex_pdf.cli:main"

{codex_pdf-1.7.2 → codex_pdf-1.8.0}/src/codex_pdf/api/main.py

@@ -64,6 +64,11 @@ from starlette.middleware.base import BaseHTTPMiddleware
 from codex_pdf.api.auth import authenticate
 from codex_pdf.api.blob_store import make_blob_store
 from codex_pdf.api.cache import cache_key, make_cache
+from codex_pdf.api.retention import (
+    make_retention_store,
+    normalise_tenant,
+    parse_retention_consent,
+)
 from codex_pdf.api.warmup import warmup_worker
 from codex_pdf.api.url_ingest import fetch_pdf_from_url
 from codex_pdf.color import (
@@ -163,6 +168,7 @@ def _record(endpoint: str, status_code: int, duration: float) -> None:
 
 _cache = make_cache()
 _blob_store = make_blob_store()
+_retention_store = make_retention_store()
 
 
 def _repo_root() -> Path:
@@ -790,7 +796,11 @@ def _pre_render_bg(raw: bytes) -> None:
 
 
 async def _extract_impl(
-    request: Request, pdf: UploadFile | None, *, endpoint_label: str
+    request: Request,
+    pdf: UploadFile | None,
+    *,
+    endpoint_label: str,
+    retain_form_value: str | None = None,
 ) -> JSONResponse:
     started = time.perf_counter()
     try:
@@ -805,6 +815,7 @@ async def _extract_impl(
             payload["pdf_sha256"] = sha
         # Warm the page-1 render cache in the background — don't block the response.
         asyncio.ensure_future(loop.run_in_executor(None, _pre_render_bg, raw))
+        await _maybe_retain(request, raw, sha, payload, retain_form_value)
         _record(endpoint_label, 200, time.perf_counter() - started)
         return JSONResponse(payload)
     except HTTPException as exc:
@@ -819,21 +830,116 @@ async def _extract_impl(
         ) from exc
 
 
+async def _maybe_retain(
+    request: Request,
+    raw: bytes,
+    sha: str,
+    payload: dict[str, Any],
+    retain_form_value: str | None,
+) -> None:
+    """Audit-log the consent decision; persist to S3 if opted in.
+
+    Audit log fires on every extract regardless of consent so the
+    "off" path is observable. Persistence only runs when consent is
+    affirmative AND retention is configured. A persist failure logs
+    but does not break the extract response — the user already got
+    their answer.
+    """
+    decision = parse_retention_consent(
+        retain_form_value,
+        request.headers.get("x-compile-retain-for-training"),
+    )
+    tenant = normalise_tenant(request.headers.get("x-codex-tenant"))
+    request_id = request.headers.get("x-codex-request-id") or ""
+    configured = _retention_store is not None
+    logger.info(
+        "extract_consent decision=%s source=%s mismatch=%s tenant=%s sha=%s "
+        "request_id=%s retention_configured=%s",
+        decision.consent,
+        decision.source,
+        decision.mismatch,
+        tenant,
+        sha[:16],
+        request_id,
+        configured,
+    )
+    if not (decision.consent and _retention_store is not None):
+        return
+    try:
+        loop = asyncio.get_event_loop()
+        keys = await loop.run_in_executor(
+            None,
+            lambda: _retention_store.put(
+                pdf_bytes=raw,
+                extract_payload=payload,
+                request_id=request_id,
+                tenant=tenant,
+                sha256=sha,
+                codex_version=VERSION,
+                consent_source=decision.source,
+            ),
+        )
+        logger.info(
+            "extract_retained sha=%s tenant=%s keys=%s",
+            sha[:16],
+            tenant,
+            list(keys.values()),
+        )
+    except Exception:
+        logger.exception("retention persist failed sha=%s tenant=%s", sha[:16], tenant)
+
+
 @app.post("/extract", include_in_schema=False, dependencies=[Depends(authenticate)])
 async def extract_root_endpoint(
     request: Request,
     pdf: UploadFile | None = File(default=None),
+    retain_for_training: str | None = Form(default=None),
 ) -> JSONResponse:
-    return await _extract_impl(request, pdf, endpoint_label="extract")
+    return await _extract_impl(
+        request, pdf, endpoint_label="extract", retain_form_value=retain_for_training
+    )
 
 
 @app.post("/v1/extract", dependencies=[Depends(authenticate)])
 async def extract_endpoint(
     request: Request,
     pdf: UploadFile | None = File(default=None),
+    retain_for_training: str | None = Form(default=None),
 ) -> JSONResponse:
     """Extract a CodexDocument from an uploaded PDF or remote URL."""
-    return await _extract_impl(request, pdf, endpoint_label="extract")
+    return await _extract_impl(
+        request, pdf, endpoint_label="extract", retain_form_value=retain_for_training
+    )
+
+
+class _RetentionDeleteRequest(BaseModel):
+    sha256: str = Field(..., description="Lower-case hex SHA-256 of the PDF to erase.")
+
+
+@app.post("/v1/retention/delete", dependencies=[Depends(authenticate)])
+async def retention_delete_endpoint(payload: _RetentionDeleteRequest) -> JSONResponse:
+    """Erase every retained object for ``sha256`` (DSAR endpoint).
+
+    503 when retention is not configured (operator hasn't set
+    ``CODEX_RETAIN_BUCKET``). 400 on a malformed sha256. ``deleted=0``
+    when no objects matched — DSAR replay is idempotent, callers
+    don't need to distinguish "never stored" from "already erased".
+    """
+    if _retention_store is None:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="retention not configured (CODEX_RETAIN_BUCKET unset)",
+        )
+    sha = payload.sha256.strip().lower()
+    loop = asyncio.get_event_loop()
+    try:
+        deleted = await loop.run_in_executor(None, _retention_store.delete, sha)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)
+        ) from exc
+    logger.info("retention_delete sha=%s deleted=%d", sha[:16], deleted)
+    return JSONResponse({"sha256": sha, "deleted": deleted})
 
 
 async def _read_probe_pdf(request: Request, pdf: UploadFile | None) -> bytes:

codex_pdf-1.8.0/src/codex_pdf/api/retention.py

@@ -0,0 +1,312 @@
+"""Opt-in PDF retention for the marketing demo.
+
+When a request to ``/v1/extract`` carries an explicit "yes, retain for
+training" signal, the codex sidecar persists the input PDF, the
+extract response, and a tiny metadata object to S3-compatible storage
+under a hive-partitioned key. Everything else (no flag, ``false``
+flag, storage unconfigured) is a no-op — the bytes leave memory the
+moment the response ships, exactly like before.
+
+Object key layout::
+
+    {prefix}/tenant={tenant}/dt={YYYY-MM-DD}/sha256={hex64}/document.pdf
+    {prefix}/tenant={tenant}/dt={YYYY-MM-DD}/sha256={hex64}/extract.json
+    {prefix}/tenant={tenant}/dt={YYYY-MM-DD}/sha256={hex64}/meta.json
+
+Hive partitioning makes the bucket Athena/Glue-queryable later
+without a migration. ``dt=`` makes an S3 Lifecycle rule trivial
+(operator-owned — the app does *not* try to manage lifecycle
+policies). ``sha256=`` dedupes idempotent re-uploads of the same
+file on the same day.
+
+``CODEX_RETAIN_TTL_DAYS`` is informational: the app writes the
+declared retention window into ``meta.json`` and the audit log, but
+expiry is enforced by the bucket's lifecycle rule the operator
+configures out-of-band.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Protocol
+
+logger = logging.getLogger(__name__)
+
+_TRUE_TOKENS = frozenset({"true", "1", "yes", "on"})
+_TENANT_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,62}$")
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+
+
+# ---------------------------------------------------------------------------
+# Consent parsing
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ConsentDecision:
+    consent: bool
+    source: str  # "form" | "header" | "both" | "none"
+    mismatch: bool  # form != header when both were present
+
+
+def _truthy(value: str | None) -> bool | None:
+    """Return ``True``/``False`` for a recognised token, ``None`` if absent.
+
+    Recognised true tokens: ``true``, ``1``, ``yes``, ``on`` (case-
+    insensitive, whitespace-stripped). Anything else — including
+    ``"false"``, ``"0"``, ``"no"``, ``"off"``, ``""``, garbage — is
+    explicitly false. The three-valued return lets the caller tell
+    "user said no" from "user said nothing" when reconciling form
+    against header.
+    """
+    if value is None:
+        return None
+    token = value.strip().lower()
+    if not token:
+        return None
+    return token in _TRUE_TOKENS
+
+
+def parse_retention_consent(
+    form_value: str | None, header_value: str | None
+) -> ConsentDecision:
+    """Reconcile the form-field and header signals from the demo uploader.
+
+    The browser checkbox is canonical; the header is fallback only
+    when the form field is absent. If both are present and disagree,
+    the form wins and the mismatch is flagged so the audit log can
+    surface the integration bug without overriding user intent.
+    """
+    form = _truthy(form_value)
+    header = _truthy(header_value)
+
+    if form is None and header is None:
+        return ConsentDecision(consent=False, source="none", mismatch=False)
+    if form is None:
+        return ConsentDecision(consent=bool(header), source="header", mismatch=False)
+    if header is None:
+        return ConsentDecision(consent=form, source="form", mismatch=False)
+
+    mismatch = form != header
+    if form and header:
+        return ConsentDecision(consent=True, source="both", mismatch=False)
+    return ConsentDecision(consent=form, source="form", mismatch=mismatch)
+
+
+def normalise_tenant(raw: str | None) -> str:
+    """Validate ``X-Codex-Tenant`` and fall back to ``default``.
+
+    Invalid values fall back rather than 400ing so an upstream typo
+    doesn't break the user-facing extract. The fallback + warning is
+    visible in the audit log.
+    """
+    if raw is None:
+        return "default"
+    candidate = raw.strip().lower()
+    if not candidate:
+        return "default"
+    if not _TENANT_RE.match(candidate):
+        logger.warning("retention tenant header rejected raw=%r → default", raw)
+        return "default"
+    return candidate
+
+
+# ---------------------------------------------------------------------------
+# Storage
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class RetentionConfig:
+    bucket: str
+    prefix: str
+    ttl_days: int
+    endpoint_url: str | None
+    region: str
+    access_key_id: str | None
+    secret_access_key: str | None
+
+    @classmethod
+    def from_env(cls) -> RetentionConfig | None:
+        bucket = (os.environ.get("CODEX_RETAIN_BUCKET") or "").strip()
+        if not bucket:
+            return None
+        try:
+            ttl_days = int(os.environ.get("CODEX_RETAIN_TTL_DAYS", "90"))
+        except ValueError:
+            logger.warning("CODEX_RETAIN_TTL_DAYS is not an int → defaulting to 90")
+            ttl_days = 90
+        return cls(
+            bucket=bucket,
+            prefix=(os.environ.get("CODEX_RETAIN_PREFIX") or "").strip().strip("/"),
+            ttl_days=ttl_days,
+            endpoint_url=(os.environ.get("CODEX_RETAIN_ENDPOINT_URL") or "").strip() or None,
+            region=(os.environ.get("CODEX_RETAIN_REGION") or "us-east-1").strip(),
+            access_key_id=(os.environ.get("CODEX_RETAIN_ACCESS_KEY_ID") or "").strip() or None,
+            secret_access_key=(
+                (os.environ.get("CODEX_RETAIN_SECRET_ACCESS_KEY") or "").strip() or None
+            ),
+        )
+
+
+class _S3Client(Protocol):
+    def put_object(self, **kwargs: Any) -> Any: ...
+    def list_objects_v2(self, **kwargs: Any) -> Any: ...
+    def delete_objects(self, **kwargs: Any) -> Any: ...
+
+
+def _utc_date() -> str:
+    return datetime.now(timezone.utc).date().isoformat()
+
+
+def _utc_ts() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _object_key(prefix: str, tenant: str, dt: str, sha: str, suffix: str) -> str:
+    parts = [
+        p for p in (prefix, f"tenant={tenant}", f"dt={dt}", f"sha256={sha}", suffix) if p
+    ]
+    return "/".join(parts)
+
+
+class RetentionStore:
+    """Three-object-per-event S3 writer.
+
+    The S3 client is constructor-injected so tests substitute a
+    ``MagicMock`` without depending on boto3 (or moto). Production
+    instantiation goes through ``make_retention_store()``.
+    """
+
+    def __init__(self, config: RetentionConfig, client: _S3Client) -> None:
+        self._config = config
+        self._client = client
+
+    @property
+    def config(self) -> RetentionConfig:
+        return self._config
+
+    def put(
+        self,
+        *,
+        pdf_bytes: bytes,
+        extract_payload: dict[str, Any],
+        request_id: str,
+        tenant: str,
+        sha256: str,
+        codex_version: str,
+        consent_source: str,
+    ) -> dict[str, str]:
+        """Write ``document.pdf``, ``extract.json``, ``meta.json``.
+
+        Returns the three object keys for the audit log.
+        """
+        dt = _utc_date()
+        meta: dict[str, Any] = {
+            "request_id": request_id,
+            "ts": _utc_ts(),
+            "sha256": sha256,
+            "content_length": len(pdf_bytes),
+            "tenant": tenant,
+            "codex_version": codex_version,
+            "consent_source": consent_source,
+            "retention_window_days": self._config.ttl_days,
+        }
+        pdf_key = _object_key(self._config.prefix, tenant, dt, sha256, "document.pdf")
+        extract_key = _object_key(self._config.prefix, tenant, dt, sha256, "extract.json")
+        meta_key = _object_key(self._config.prefix, tenant, dt, sha256, "meta.json")
+
+        self._client.put_object(
+            Bucket=self._config.bucket,
+            Key=pdf_key,
+            Body=pdf_bytes,
+            ContentType="application/pdf",
+        )
+        self._client.put_object(
+            Bucket=self._config.bucket,
+            Key=extract_key,
+            Body=json.dumps(extract_payload, sort_keys=True, separators=(",", ":")).encode(
+                "utf-8"
+            ),
+            ContentType="application/json",
+        )
+        self._client.put_object(
+            Bucket=self._config.bucket,
+            Key=meta_key,
+            Body=json.dumps(meta, sort_keys=True, separators=(",", ":")).encode("utf-8"),
+            ContentType="application/json",
+        )
+        return {"pdf": pdf_key, "extract": extract_key, "meta": meta_key}
+
+    def delete(self, sha256: str) -> int:
+        """Erase every object with ``sha256={sha}/`` in its key.
+
+        Scans every ``dt=`` / ``tenant=`` partition. S3 has no native
+        sha-suffix search, but a 90-day window with a couple of
+        tenants is small enough that the linear scan is fine — and
+        avoids a parallel index we'd have to keep consistent.
+        """
+        if not _SHA256_RE.match(sha256):
+            raise ValueError(f"invalid sha256: {sha256!r}")
+        matches: list[dict[str, str]] = []
+        token: str | None = None
+        list_prefix = f"{self._config.prefix}/" if self._config.prefix else ""
+        while True:
+            kwargs: dict[str, Any] = {
+                "Bucket": self._config.bucket,
+                "Prefix": list_prefix,
+            }
+            if token:
+                kwargs["ContinuationToken"] = token
+            resp = self._client.list_objects_v2(**kwargs)
+            for entry in resp.get("Contents", []) or []:
+                key = entry.get("Key", "")
+                if f"/sha256={sha256}/" in key:
+                    matches.append({"Key": key})
+            if not resp.get("IsTruncated"):
+                break
+            token = resp.get("NextContinuationToken")
+            if not token:
+                break
+
+        deleted = 0
+        for i in range(0, len(matches), 1000):
+            batch = matches[i : i + 1000]
+            self._client.delete_objects(
+                Bucket=self._config.bucket, Delete={"Objects": batch}
+            )
+            deleted += len(batch)
+        return deleted
+
+
+def make_retention_store() -> RetentionStore | None:
+    """Build a production ``RetentionStore`` from env, or return ``None``.
+
+    ``None`` is the explicit "feature off" sentinel. The boto3 import
+    is deferred so the base wheel doesn't pull boto3 in unless the
+    operator opts in via ``CODEX_RETAIN_BUCKET``.
+    """
+    config = RetentionConfig.from_env()
+    if config is None:
+        return None
+    try:
+        import boto3  # type: ignore[import-not-found]
+    except ImportError:
+        logger.warning(
+            "CODEX_RETAIN_BUCKET set but boto3 is not installed — "
+            "install codex-pdf[retain] to enable retention. Falling back to disabled."
+        )
+        return None
+    client_kwargs: dict[str, Any] = {"region_name": config.region}
+    if config.endpoint_url:
+        client_kwargs["endpoint_url"] = config.endpoint_url
+    if config.access_key_id and config.secret_access_key:
+        client_kwargs["aws_access_key_id"] = config.access_key_id
+        client_kwargs["aws_secret_access_key"] = config.secret_access_key
+    client = boto3.client("s3", **client_kwargs)
+    return RetentionStore(config, client)

{codex_pdf-1.7.2 → codex_pdf-1.8.0}/src/codex_pdf/version.py

@@ -38,5 +38,5 @@ or unreachable Redis service can never crash the codex API.
 1.3.0 (prior): SSRF hardening + /v1/walk/type4 endpoint.
 """
 
-VERSION = "1.7.2"
+VERSION = "1.8.0"
 __version__ = VERSION

codex_pdf-1.8.0/tests/test_retention_consent.py

@@ -0,0 +1,94 @@
+"""Unit tests for the retention consent parser.
+
+The marketing demo sends both a form field (``retain_for_training``)
+and a header (``X-Compile-Retain-For-Training``). These tests pin the
+full truth matrix: missing/present × every token variant × form-vs-
+header reconciliation. Anything outside the documented true tokens
+must be false — a typo like ``"yes please"`` is not an opt-in.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from codex_pdf.api.retention import (
+    ConsentDecision,
+    normalise_tenant,
+    parse_retention_consent,
+)
+
+
+@pytest.mark.parametrize(
+    "form,header,want_consent,want_source,want_mismatch",
+    [
+        # Neither present → off.
+        (None, None, False, "none", False),
+        ("", None, False, "none", False),
+        (None, "", False, "none", False),
+        ("   ", "   ", False, "none", False),
+        # Header-only paths.
+        (None, "true", True, "header", False),
+        (None, "TRUE", True, "header", False),
+        (None, "1", True, "header", False),
+        (None, "yes", True, "header", False),
+        (None, "on", True, "header", False),
+        (None, "false", False, "header", False),
+        (None, "0", False, "header", False),
+        (None, "no", False, "header", False),
+        (None, "off", False, "header", False),
+        (None, "maybe", False, "header", False),
+        # Form-only paths.
+        ("true", None, True, "form", False),
+        ("TRUE", None, True, "form", False),
+        ("1", None, True, "form", False),
+        ("yes", None, True, "form", False),
+        ("on", None, True, "form", False),
+        ("false", None, False, "form", False),
+        ("0", None, False, "form", False),
+        ("no", None, False, "form", False),
+        ("off", None, False, "form", False),
+        # Both present + agree.
+        ("true", "true", True, "both", False),
+        ("1", "yes", True, "both", False),
+        ("false", "false", False, "form", False),
+        # Both present + disagree → form wins, mismatch flagged.
+        ("true", "false", True, "form", True),
+        ("false", "true", False, "form", True),
+        ("yes", "no", True, "form", True),
+        # Whitespace + case tolerance.
+        ("  Yes  ", None, True, "form", False),
+        (None, "  ON\n", True, "header", False),
+    ],
+)
+def test_parse_retention_consent_matrix(
+    form: str | None,
+    header: str | None,
+    want_consent: bool,
+    want_source: str,
+    want_mismatch: bool,
+) -> None:
+    got = parse_retention_consent(form, header)
+    assert got == ConsentDecision(
+        consent=want_consent, source=want_source, mismatch=want_mismatch
+    )
+
+
+@pytest.mark.parametrize(
+    "raw,want",
+    [
+        (None, "default"),
+        ("", "default"),
+        ("   ", "default"),
+        ("compile-marketing", "compile-marketing"),
+        ("COMPILE-Marketing", "compile-marketing"),
+        ("acme42", "acme42"),
+        # Invalid → silent fallback (logged).
+        ("under_score", "default"),
+        ("has space", "default"),
+        ("-leadingdash", "default"),
+        ("a" * 64, "default"),
+        ("a/b", "default"),
+    ],
+)
+def test_normalise_tenant(raw: str | None, want: str) -> None:
+    assert normalise_tenant(raw) == want