fix: align 4.0.1 release contracts

Author: padolsey

CHANGELOG.md

@@ -47,14 +47,19 @@ changed or removed.
   `bot_context` reaches the Oversight analysis prompt, and trajectory roles
   are `user` or `assistant`. The `screen()` docstring names the 2027-01-01
   sunset the runtime warning already carried.
+- Oversight ingest documentation now states the deployed 5 MB body limit.
+  Analyze documentation distinguishes retained event metadata from the
+  conversation and full-result records created by ingest. Signpost's
+  `urgent` option is consistently described as a ranking hint.
+- Package metadata identifies the SDK as beta, matching the service status.
 
 ## 4.0.0 - 2026-09-03
 
 Realigns the SDK with the API at commit 73c477c. Every v1 response model is now
 pinned to a sanitized live capture under `tests/fixtures/` (the deprecated
 `/v0/screen` models have none), and the two
 versions that never reached PyPI (2.3.1, 3.0.0) are folded into this release.
-The last published version is 2.3.0.
+The preceding published version was 2.3.0.
 
 ### Breaking changes
 

README.md

@@ -215,7 +215,7 @@ In demo mode the call returns `OversightDemoAnalyzeResponse` with `mode`
 Batch ingest stores results for the dashboard and cross-session tracking. It
 accepts up to 300 conversations per call, bills $0.10 each before analysis,
 and returns when processing has finished (`status` is `complete` or `failed`).
-The request body is capped at 512 KB, so a batch near the count limit must
+The request body is capped at 5 MB, so a batch near the count limit must
 consist of short conversations. `webhook_url` is a legacy per-request callback:
 the API POSTs an unsigned `ingestion_complete` JSON summary there when the batch
 completes. The signed `oversight.ingestion.complete` event is delivered to

pyproject.toml

@@ -14,7 +14,7 @@ authors = [
 ]
 keywords = ["safety", "ai", "risk", "classification", "mental-health", "crisis"]
 classifiers = [
-    "Development Status :: 5 - Production/Stable",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",

src/nope_net/client.py

@@ -405,9 +405,11 @@ def oversight_analyze(
         """
         Analyze one conversation for harmful AI behaviours ($0.10 per call).
 
-        Synchronous; nothing is stored. Use :meth:`oversight_ingest` for
-        persistent storage and the dashboard. Turn numbers in the result are
-        1-based and count assistant turns.
+        The call is synchronous and does not write conversation content or full
+        results to the Oversight application database. Operational and
+        analysis-event metadata is retained under the public policy. Use
+        :meth:`oversight_ingest` for persistent dashboard storage. Turn numbers
+        in the result are 1-based and count assistant turns.
 
         Args:
             conversation: ``conversation_id``, ``messages`` (role ``user``, ``assistant``
@@ -489,7 +491,7 @@ def oversight_ingest(
             conversations: Conversations (at most 300), each with a ``conversation_id``
                 and non-empty ``messages``; any sequence of dicts, mappings or
                 ``OversightConversation`` models. The request body is capped at
-                512 KB, so a batch near the count limit must consist of short
+                5 MB, so a batch near the count limit must consist of short
                 conversations.
             webhook_url: Legacy per-request callback. The API POSTs an unsigned
                 ``{event: 'ingestion_complete', timestamp, ingestion_id,
@@ -563,7 +565,8 @@ def signpost(
             populations: Populations from ``nope_net.POPULATIONS`` (e.g. "youth").
             subdivisions: ISO 3166-2 codes within the country (e.g. "GB-SCT").
             limit: Maximum resources (the API clamps to 10).
-            urgent: Only 24/7 resources.
+            urgent: Ranking hint. Places 24/7 resources first among ties on
+                relevance and priority tier without filtering other matches.
 
         Returns:
             SignpostResponse with ``resources`` (and ``primary``/``secondary`` when

src/nope_net/types.py

@@ -719,7 +719,8 @@ class SignpostConfig(BaseModel):
     """Maximum number of resources to return (the API clamps to 10)."""
 
     urgent: Optional[bool] = None
-    """Only return 24/7 urgent resources."""
+    """Ranking hint. Places 24/7 resources first among ties on relevance and
+    priority tier without filtering other matches."""
 
 
 class SignpostSmartConfig(BaseModel):

tests/contract/test_documentation_contract.py

@@ -0,0 +1,48 @@
+"""Public and maintainer-facing claims that must track the deployed API."""
+
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def read(relative_path: str) -> str:
+    return (ROOT / relative_path).read_text(encoding="utf-8")
+
+
+def test_oversight_limits_and_storage_are_route_specific() -> None:
+    readme = read("README.md")
+    client = read("src/nope_net/client.py")
+    client_prose = " ".join(client.split())
+
+    assert "request body is capped at 5 MB" in readme
+    assert "request body is capped at 512 KB" not in readme
+    assert "5 MB, so a batch near the count limit" in client_prose
+    assert "Synchronous; nothing is stored" not in client
+    assert "does not write conversation content or full results" in client_prose
+
+
+def test_urgent_is_documented_as_ranking() -> None:
+    client = read("src/nope_net/client.py")
+    types = read("src/nope_net/types.py")
+
+    assert "urgent: Only 24/7 resources" not in client
+    assert "Only return 24/7 urgent resources" not in types
+    assert "24/7 resources first among ties" in client
+    assert "Ranking hint" in types
+
+
+def test_deployed_ticket_references_are_absent_from_fixture_docs() -> None:
+    assert "API fix A-" not in read("tests/fixtures/README.md")
+    assert "The last published version is 2.3.0" not in read("CHANGELOG.md")
+
+
+def test_webhook_delivery_test_describes_distinct_ids() -> None:
+    source = read("tests/unit/test_webhook_delivery_id.py")
+    assert "sends the payload's event_id as X-NOPE-Delivery-ID" not in source
+    assert "stored delivery id as X-NOPE-Delivery-ID" in source
+
+
+def test_package_metadata_marks_the_beta_status_honestly() -> None:
+    project = read("pyproject.toml")
+    assert "Development Status :: 4 - Beta" in project
+    assert "Development Status :: 5 - Production/Stable" not in project

tests/fixtures/README.md

@@ -13,12 +13,12 @@ the sanitization rules below.
 | `evaluate/` | `auth.benign.json` | `POST /v1/evaluate`, one benign message, `risks: []` |
 | | `try.gb.json` | `POST /v1/try/evaluate`, three messages, GB resources, `subdivision_codes`, `metadata.model` |
 | | `try.us.json` | `POST /v1/try/evaluate`, one message; requested with `config.country: GB` before the demo route honoured it, so the resources are US |
-| | `try.gb.no-resources.json` | `POST /v1/try/evaluate` after API fix A-1: `config.country: GB`, `include_resources: false`, no resources returned |
+| | `try.gb.no-resources.json` | `POST /v1/try/evaluate`: `config.country: GB`, `include_resources: false`, no resources returned |
 | | `try.gb.text.json` | `POST /v1/try/evaluate` with `text`, `metadata.input_format: text_blob` |
 | `oversight/` | `try.full.json`, `try.fast.json`, `auth.fast.json` | the demo full, demo fast and authenticated fast envelopes |
 | `ocular/` | `try.json`, `auth.json`, `auth.per-turn.json` | demo wire (with `heads`, `detail`), customer wire, and the customer wire with `per_turn: true` (`trajectory`, `trajectory_shape`, roles `user`/`assistant`) |
-| `signpost/` | `auth.gb.json`, `try.smart.json`, `search.auth.json`, `search.auth.mixed-contacts.json`, `countries.json`, `detect-country.miss.json`, `by-id.json` | basic (authenticated; resources carry `id` after API fix A-6), demo smart, by-id, search (authenticated; the mixed-contacts capture from the first live run shows contacts without `tier` or `value` and chat contacts carrying `url`), countries, detect-country miss |
-| `billing/` | `balance.json`, `usage.json`, `pricing.json` | `GET /v1/billing/*` after API fix A-5 (balance and usage figures replaced) |
+| `signpost/` | `auth.gb.json`, `try.smart.json`, `search.auth.json`, `search.auth.mixed-contacts.json`, `countries.json`, `detect-country.miss.json`, `by-id.json` | basic authenticated results with resource `id`, demo smart, by-id, search (the mixed-contacts capture shows contacts without `tier` or `value` and chat contacts carrying `url`), countries, detect-country miss |
+| `billing/` | `balance.json`, `usage.json`, `pricing.json` | Current `GET /v1/billing/*` wire shapes (balance and usage figures replaced) |
 | `errors/` | `400.*.json`, `401.*.json`, `404.*.json`, `413.*.json` | error bodies as served; 402, 429 and 503 are source-derived and live in the tests |
 | `headers/` | `*.txt` | rate-limit and balance headers (balance values replaced) |
 | `webhooks/` | `*.json` | payloads built by the API's own builders and signed with a fixed test secret |

tests/unit/test_webhook_delivery_id.py

@@ -58,7 +58,7 @@ def test_verify_request_without_delivery_header() -> None:
 
 
 def test_live_fixture_delivery_id_is_distinct_from_payload_event_id() -> None:
-    """The API sends the payload's event_id as X-NOPE-Delivery-ID (signature.ts)."""
+    """The API sends the stored delivery id as X-NOPE-Delivery-ID."""
     for event in ("evaluate.alert", "oversight.alert", "oversight.ingestion.complete", "test.ping"):
         fx = load_fixture(f"webhooks/{event}.json")
         verified = Webhook.verify_request(