release: 0.7.0 — thin-client refactor (#34)

BREAKING CHANGES
----------------

SDK is now a thin client. All enforcement decisions arrive from the
backend via /api/v1/gate and /api/v1/execute. Local policy
enforcement, its dataclass, and its hardcoded thresholds are removed.

Removed:
  * class Policy, Policy.default_local(), Policy.strict_local(),
    Policy.from_dict() (was at nullrun.runtime.Policy)
  * NullRunRuntime.policy property
  * NullRunRuntime(policy=...) constructor kwarg
  * NullRunStatus.active_policy, .fallback_policy,
    .fallback_reason, .last_policy_fetch,
    .last_policy_fetch_age_seconds fields
  * Transport.fetch_policy() method
  * Transport.clear_policy_cache() method
  * FallbackMode.CACHED enum value
  * Local loop/rate detectors: LoopTracker, RateTracker,
    LocalDecision classes
  * NullRunRuntime._local_check(), _loop_tracker, _rate_tracker
    instance attrs
  * _local_loop_threshold, _local_rate_limit (hardcoded 6/1000)
  * CachedDecision, PolicyCache transport classes
  * NULLRUN_FALLBACK_MODE env var
  * NULLRUN_POLICY_FAIL_OPEN env var (backend is authoritative)
  * NullRunRuntime._fetch_policy() method
  * WS on_policy_invalidated callback

Migration: if you need to display policy values in a UI, fetch them
directly via GET /api/v1/orgs/{org_id}/policies. The SDK no longer
mirrors them.

Audit: Drift D-01 from 2026-06-26 SDK↔backend audit
(PolicyResponse lacked fields SDK expected; local defaults silently
widened limits).

Transport finalizer behavior change
-----------------------------------

Transport._atexit_flush_safe is now a no-op that emits a single
DEBUG log line. It does NOT persist buffered events to the WAL
anymore — by the time weakref.finalize fires, self._buffer /
self._lock / self._client are already gone. Crash-safety now lives
exclusively in stop() and the context-manager pattern. Callers who
relied on the implicit on-exit WAL flush MUST switch to:

    with nullrun.Transport(api_url=..., api_key=...) as t:
        ...

or call t.stop() explicitly before process exit.

Tests
-----

* tests/test_signal_safety.py::TestAtexitViaWeakref rewritten to
  pin the new no-op-finalizer contract (was written against an
  intended but-unimplemented WAL-persist finalizer).
* tests/test_deprecation_warnings.py removed (NULLRUN_FALLBACK_MODE
  env var is gone; deprecation warning is moot).
* tests/test_no_local_policy.py added (pins absence of
  NullRunRuntime._local_check and the local Policy dataclass).
* Various test updates reflecting runtime/transport refactors
  (-1883 / +1432 in tests/, mostly deletions of policy- and
  fallback-mode-specific cases).

Other
-----

* pyproject.toml: version bumped 0.6.1 -> 0.7.0 (was inconsistent
  with __version__.py before this commit).
* CHANGELOG.md: full 0.7.0 entry covering BREAKING CHANGES, the
  transport-finalizer contract change, and migration guidance.

Verification (local on Windows / Python 3.14.2):
  pytest        913 passed, 13 skipped (0:08:50)
  ruff check    clean on src/ and tests/
  mypy src/     clean on 26 source files

Author: maltsev-dev

CHANGELOG.md

@@ -7,6 +7,74 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
 ---
 
+## [0.7.0] - 2026-06-26
+
+### BREAKING CHANGES
+
+SDK is now a thin client. All enforcement decisions arrive from the
+backend via `/api/v1/gate` and `/api/v1/execute`. Local policy
+enforcement, its dataclass, and its hardcoded thresholds are removed.
+
+**Removed:**
+
+- `class Policy`, `Policy.default_local()`, `Policy.strict_local()`,
+  `Policy.from_dict()` (was at `nullrun.runtime.Policy`)
+- `NullRunRuntime.policy` property
+- `NullRunRuntime(policy=...)` constructor kwarg
+- `NullRunStatus.active_policy`, `.fallback_policy`,
+  `.fallback_reason`, `.last_policy_fetch`,
+  `.last_policy_fetch_age_seconds` fields
+- `Transport.fetch_policy()` method
+- `Transport.clear_policy_cache()` method
+- `FallbackMode.CACHED` enum value (gate-decision fallback)
+- Local loop/rate detectors: `LoopTracker`, `RateTracker`,
+  `LocalDecision` classes
+- `NullRunRuntime._local_check()`, `_loop_tracker`, `_rate_tracker`
+  instance attrs
+- `_local_loop_threshold`, `_local_rate_limit` instance attrs
+  (hardcoded 6/1000)
+- `CachedDecision`, `PolicyCache` transport classes (tied to the
+  removed CACHED fallback mode)
+- `NULLRUN_FALLBACK_MODE` env var
+- `NULLRUN_POLICY_FAIL_OPEN` env var (no longer needed — backend is
+  authoritative)
+- `NullRunRuntime._fetch_policy()` method (no local policy fetch on
+  init)
+- WS `on_policy_invalidated` callback (no local policy to invalidate)
+
+**Migration:**
+
+If you need to display policy values in a UI, fetch them directly
+via `GET /api/v1/orgs/{org_id}/policies`. The SDK no longer mirrors
+them.
+
+**Audit:** Drift D-01 from 2026-06-26 SDK↔backend audit
+(`PolicyResponse` lacked fields SDK expected; local defaults silently
+widened limits).
+
+### Transport finalizer behavior change
+
+`Transport._atexit_flush_safe` is now a no-op that emits a single
+`DEBUG` log line. It does NOT persist buffered events to the WAL
+anymore — by the time `weakref.finalize` fires, `self._buffer` /
+`self._lock` / `self._client` are already gone, so any attempt to
+write them would either no-op or crash. **Crash-safety now lives
+exclusively in `stop()` and the context-manager pattern.** Callers
+who relied on the implicit on-exit WAL flush must switch to:
+
+```python
+with nullrun.Transport(api_url=..., api_key=...) as t:
+    # use t; __exit__ calls stop() which calls _persist_to_wal
+    ...
+```
+
+or call `t.stop()` explicitly before process exit. A `DEBUG` log
+line "Transport finalizer fired without explicit stop(); remaining
+events may be lost" is the user-visible signal that events were
+dropped.
+
+---
+
 ## [0.6.1] — 2026-06-24
 
 Additive release — Layers 1, 2, and 3 of the "give the user a chance"

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nullrun"
-version = "0.6.1"
+version = "0.7.0"
 description = "NullRun Python SDK — Enforcement gateway for AI agents."
 readme = "README.md"
 license = { text = "Apache-2.0" }

src/nullrun/__init__.py

@@ -247,15 +247,30 @@ def my_agent():
     import nullrun.runtime as _rt_mod
     from nullrun.runtime import NullRunRuntime
 
-    # Phase 0.3.1: the three singleton slots (NullRunRuntime._instance,
-    # _rt_mod._runtime, _dec_mod._runtime) must all be assigned
-    # atomically. Without a lock, concurrent init() calls from
-    # multiple threads can leave the three slots pointing at two
-    # different runtimes. The failure mode is silent — the
-    # decorator's @protect wrapper reads _dec._runtime once and
-    # never re-resolves, so a missed assignment drops every
-    # span_start/span_end event for that runtime.
+    # C3 fix: shut down any existing runtime before constructing a new
+    # one. Without this, calling init() twice (or init() after a
+    # previous init() without an explicit shutdown()) leaves the prior
+    # daemon threads — transport flush, WS control plane, coverage
+    # reporter — running against the orphaned runtime. They keep
+    # burning CPU, hold sockets open, and can write to stale module
+    # slots that no longer reflect the active singleton.
+    #
+    # shutdown() is best-effort: if the previous runtime is mid-shutdown
+    # or in an unrecoverable state, we log and proceed so the new
+    # runtime can still come up.
     with _init_lock:
+        existing = NullRunRuntime._instance
+        if existing is not None:
+            logger.warning(
+                "nullrun.init() called while a previous runtime is "
+                "still alive; shutting down the old one to avoid "
+                "orphan threads (C3 fix)."
+            )
+            try:
+                existing.shutdown()
+            except Exception as e:  # noqa: BLE001 — best-effort
+                logger.warning("previous runtime shutdown raised during init(): %s", e)
+
         runtime = NullRunRuntime(
             api_key=api_key,
             api_url=api_url,

src/nullrun/__version__.py

@@ -1,4 +1,4 @@
 """NullRun Platform SDK."""
 
-__version__ = "0.6.1"
+__version__ = "0.7.0"
 __platform_version__ = "1.0.0"

src/nullrun/observability/status.py

@@ -32,15 +32,20 @@
   * ``"misconfigured"`` — no api_key, or ``init()`` raised a
     config error and the runtime was never bound. The SDK is
     not operating; fix the config.
-  * ``"offline"`` — backend is not reachable AND no cached
-    policy exists. Every cost-bearing call will be rejected
-    by the strict-local fallback. Fix the network / backend.
-  * ``"degraded"`` — one or more of: WS disconnected, using
-    cached policy after a recent failure, circuit breaker
-    open, workflow state != Normal. The SDK is operating but
-    with reduced guarantees. Surface the ``fallback_reason``
-    or ``workflow_state.reason`` to the user.
+  * ``"offline"`` — backend is not reachable AND no successful
+    ``/gate`` call has ever landed. Every cost-bearing call will
+    be rejected by the SDK's fail-CLOSED path. Fix the network /
+    backend.
+  * ``"degraded"`` — one or more of: WS disconnected, circuit
+    breaker open, workflow state != Normal. The SDK is operating
+    but with reduced guarantees. Surface the ``workflow_state.reason``
+    to the user.
   * ``"ok"`` — everything healthy. This is the steady state.
+
+Note (0.7.0): SDK no longer maintains a local ``Policy`` cache. All
+enforcement decisions arrive from the backend via ``/gate`` and
+``/execute``. The "cached policy" degradation state from prior
+versions is gone — SDK is either talking to the backend or it isn't.
 """
 
 from __future__ import annotations
@@ -108,10 +113,16 @@ class WorkflowState:
     Mirrors the shape of the WS ``state_change`` message so the
     user can read ``status.workflow_state.state`` and know
     whether the body will run on the next call.
+
+    CP1 fix (2026-06-26): the backend WsWorkflowState enum has 5
+    variants, not 3 — Flagged and Tripped were previously silently
+    treated as Normal. The SDK now handles all 5 explicitly in
+    ``runtime.check_control_plane``; this dataclass reflects the
+    full set so the operator-facing status mirrors reality.
     """
 
     workflow_id: str
-    state: str  # "Normal" | "Paused" | "Killed"
+    state: str  # "Normal" | "Paused" | "Killed" | "Flagged" | "Tripped"
     version: int
     reason: str | None = None
 
@@ -136,13 +147,6 @@ class NullRunStatus:
     workflow_id: str | None
     api_url: str
 
-    # Policy
-    last_policy_fetch: datetime | None  # UTC
-    last_policy_fetch_age_seconds: float | None
-    active_policy: Any  # Policy | None — forward-declared
-    fallback_policy: Any  # Policy | None — last known-good
-    fallback_reason: str | None  # why fallback is in use
-
     # Connectivity
     backend_reachable: bool | None  # None = never tested
     ws_connected: bool | None  # None = not started / unknown
@@ -169,8 +173,8 @@ def summary(self) -> str:
 
         Example outputs:
             "NullRunStatus(ok, api_key=nr_live_S, org=…, wf=…)"
-            "NullRunStatus(degraded, fallback=last_good@3min, reason=5xx)"
-            "NullRunStatus(offline, no cached policy, ws=False)"
+            "NullRunStatus(degraded, wf_state=Killed, backend=unreachable)"
+            "NullRunStatus(offline, ws=False, errors=2)"
         """
         bits = [f"NullRunStatus({self.state}"]
         if self.api_key_prefix:
@@ -179,16 +183,6 @@ def summary(self) -> str:
             bits.append(f"org={self.organization_id[:8]}")
         if self.workflow_id:
             bits.append(f"wf={self.workflow_id[:8]}")
-        if self.fallback_policy and self.fallback_policy is not self.active_policy:
-            # Always show that we are on a fallback — the user
-            # sees the string "fallback" and knows to look at
-            # ``fallback_reason`` for the cause.
-            if self.last_policy_fetch_age_seconds is not None:
-                bits.append(f"fallback=last_good@{int(self.last_policy_fetch_age_seconds)}s")
-            else:
-                bits.append("fallback=last_good")
-            if self.fallback_reason:
-                bits.append(f"reason={self.fallback_reason[:40]}")
         if self.workflow_state and self.workflow_state.state != "Normal":
             bits.append(f"wf_state={self.workflow_state.state}")
         if self.backend_reachable is False: