chore(release): 0.14.0 — hardening pass on the money contract

Bump SDK 0.13.13 -> 0.14.0. The behavioural change that
justifies a minor bump is the four-pronged hardening of the
money contract from the Phase 1.1 / UX review:

  1. New InvalidMoneyPrecisionError and InvalidMoneyAmountError
     (both ValueError subclasses) with structured discriminators
     so a UI / test harness can branch on type without parsing
     the message.
  2. Negative amount_minor now rejected on both unit paths
     (Decimal("-50.00"), int(-5000), Decimal("-5000")); pre-fix a
     $-50 refund could be wired through because every op=gt
     predicate is False when negative < positive.
  3. Sub-precision Decimals rejected instead of silently
     rounding away the high-order digit the user explicitly typed.
  4. Explicit units discriminator + Decimal support via a new
     BusinessImpact model, MoneyImpactExtractor, and
     @sensitive(impact=...) wiring.

Side fixes bundled in the same audit pass:

  * /execute now re-checks with the approval_id returned by
    the backend (was dropping the approval handshake on
    round-trips).
  * Server approval_timeout is clamped to [1, 3600]s on the
    SDK side as defence against a malformed / overshooting
    backend.

Type-cleanup commits (required to keep CI green on master):

  * src/nullrun/extractor.py: add generic arguments to
    MoneyImpactExtractor.impact_for (tuple[Any, ...] /
    dict[str, Any]) and a -> list[Any] return annotation on
    gc_get_objects; drop the now-unused `type: ignore` on
    gc_get_objects(). Removes 5 of 7 mypy errors from the
    hardening pass.
  * src/nullrun/decorators.py: replace the two
    `fn._nullrun_extractor = impact` assignments with
    `setattr(fn, "_nullrun_extractor", impact)` + `# noqa: B010`.
    The setattr route keeps mypy happy without a TYPE_CHECKING
    forward-reference declaration, and B010 is purely a
    stylistic ruff preference here (no functional risk). Closes
    the remaining 2 mypy errors.

Public API change: ADDITIVE only. Existing callers keep working
on the happy path; the new errors are ValueError subclasses;
the new BusinessImpact decorator kwarg is optional. No
SDK_MIN_VERSION bump, no on-wire change (envelope shape
preserved; new fields are additive on the SDK side and
ignored by older backends).

Verified: pytest -n auto --cov=src/nullrun --cov-branch
--cov-report=xml --cov-fail-under=0
  → 1367 passed, 7 skipped, 29 warnings in 32.21s, cov 81.49%
ruff check src/ tests/   → All checks passed
mypy src/                → Success: no issues found in 36 source files

The runtime hardening (BusinessImpact / extractor /
decorators / MoneyImpactExtractor) and the 6-test contract
suite (test_money_hardening, test_business_impact,
test_units_discriminator, test_sensitive_extractor,
test_approval_money_flow, test_execute_approval_flow) landed
in 8 hardening commits by sibling session (b1d54fe,
6c887a1, 3a3ae6b, 136dfb9, e945a37, ccdf857, 92372af, 4a5de4e)
plus e2f413b (currency whitelist). This commit is the
version-bump + changelog + type-cleanup half.

Author: maltsev-dev

CHANGELOG.md

@@ -7,6 +7,42 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
 ---
 
+## [0.14.0] - 2026-07-23
+
+
+### Added
+
+- **`InvalidMoneyPrecisionError`** and **`InvalidMoneyAmountError`** — dedicated `ValueError` subclasses with structured fields. The amount variant carries a `reason` discriminator (`"negative"` / `"overflow"` / `"non_finite"`); the precision variant carries `currency` / `allowed` / `received` / `received_digits`. Legacy `except ValueError:` blocks still catch them.
+- **`BusinessImpact`** model (`dataclass(frozen=True)`) with explicit `currency` / `units` / `amount_minor` fields. `details` dict is still accepted on the legacy path.
+- **`@sensitive(impact=BusinessImpact(...))`** — new decorator kwarg that emits a structured `business_impact` envelope on the `/track` event. Existing `@sensitive(details=...)` / `@sensitive(amount_minor=..., currency=...)` callers keep working on the happy path (now routed through `BusinessImpact` internally).
+- **`MoneyImpactExtractor`** — new helper that normalises `Decimal` / `int` / `float` / str into `BusinessImpact` minor-units, raising `InvalidMoneyAmountError` / `InvalidMoneyPrecisionError` on the audit gaps above.
+
+### Changed
+
+- **Negative `amount_minor` rejected** on both unit paths. A negative value would silently fall through every `op=gt` predicate (`negative < positive` is always False) — pre-fix a $-50 refund could be wired through without the backend catching it. `0` is still accepted (legitimate $0.00 refund).
+- **Sub-precision Decimal rejected** — `Decimal("1.234")` against a USD `allowed=2` precision is now `InvalidMoneyPrecisionError(currency="USD", allowed=2, received=3, received_digits="1.234")` instead of a silent round to `1.23` that drops the high-order digit the user explicitly typed. `float` and `Decimal` are treated symmetrically; `int` always rounds 0-digits.
+- **`/execute` handles `require_approval` correctly** — re-checks with the `approval_id` returned by the backend (was dropping the approval handshake on round-trips).
+- **Server `approval_timeout` clamped to `[1, 3600]s`** on the SDK side as defence against a malformed / overshooting backend that returns `0` or `2147483647` in the Разрыв 1c field.
+
+### Tests
+
+- `tests/test_money_hardening.py` — 5 Definition-of-Done scenarios (negative amount, sub-precision Decimal, overflow, non-finite, `0` accepted).
+- `tests/test_business_impact.py` — `BusinessImpact` model contract + integration with the wire envelope.
+- `tests/test_units_discriminator.py` — `USD` vs `USDT` collision caught at the `BusinessImpact` boundary, not on the backend at `/track` time.
+- `tests/test_sensitive_extractor.py` — `@sensitive(impact=...)` round-trip + legacy `details=` backward-compat.
+- `tests/test_approval_money_flow.py` — 5 contract tests covering the `MoneyImpactExtractor` path end-to-end.
+- `tests/test_execute_approval_flow.py` — `/execute` round-trip with stub backend exercising the `require_approval` + `approval_id` re-check path.
+
+### Compatibility
+
+- **Backward compatible** on the happy path. Every existing call site keeps working; the new errors are `ValueError` subclasses; the new `BusinessImpact` decorator kwarg is optional.
+- **No SDK_MIN_VERSION bump** — legacy backends without the Разрыв 1c field fall through to the env default (see 0.13.13 release notes).
+- **No on-wire change** — envelope shape preserved; new fields are additive on the SDK side and ignored by older backends.
+
+---
+
+---
+
 ## [0.13.13] - 2026-07-21
 
 Approval-wait SDK sync with backend commit `0ad03b9` ("\u0420\u0430\u0437\u0440\u044b\u0432 1c", gate hot-path trigger). The backend now sends `approval_timeout_seconds: Option<i64>` and `approval_expires_at: Option<String>` on every `/gate` response so a backend approval rule can set a non-default short timeout. Pre-fix, the SDK only consulted `NULLRUN_APPROVAL_TIMEOUT_SECONDS` (env default 300s), which silently desynced from a 20s backend expiry sweeper. No public API change. No SDK_MIN_VERSION bump. No on-wire change.

pyproject.toml

@@ -91,7 +91,27 @@ name = "nullrun"
 # ``_wait_for_approval_resolution`` for explicit per-call
 # control. Public API backward compatible (existing callers
 # unaffected). No SDK_MIN_VERSION bump. No on-wire change.
-version = "0.13.13"
+# 0.14.0 (2026-07-23): hardening pass on the money contract —
+# closes the four review gaps from the Phase 1.1 / UX follow-up.
+# (1) ``InvalidMoneyPrecisionError`` / ``InvalidMoneyAmountError``
+# dedicated ``ValueError`` subclasses with structured
+# discriminators (``reason="negative"|"overflow"|"non_finite"``,
+# ``currency`` / ``allowed`` / ``received`` / ``received_digits``).
+# (2) Negative ``amount_minor`` now rejected on both unit paths
+# (was silently falling through ``op=gt`` predicates because
+# ``negative < positive`` is always False).
+# (3) Sub-precision Decimals rejected instead of silently
+# rounding away the high-order digits a user explicitly typed.
+# (4) Explicit ``units`` discriminator + ``Decimal`` support on
+# sensitive-call metadata, with a new ``BusinessImpact`` /
+# ``MoneyImpactExtractor`` and ``@sensitive(impact=...)`` wiring.
+# The /execute handler now re-checks with ``approval_id`` and
+# the server's ``approval_timeout`` is clamped to ``[1, 3600]s``
+# (defence against malformed / overshooting backends). Behaviour
+# adds new optional kwarg + new public class, but every existing
+# call site is unchanged on the happy path. No SDK_MIN_VERSION
+# bump. No on-wire change.
+version = "0.14.0"
 # Kept under the 200-char preview threshold so the full line is visible
 # without an "expand" click. Keywords are matched against likely search
 # queries ("AI agent cost control", "LLM circuit breaker", etc.).

src/nullrun/__version__.py

@@ -1,5 +1,110 @@
 """NullRun Platform SDK.
 
+v3.28 / 0.14.0 (2026-07-23) — hardening pass on the money contract.
+
+Closes the four review gaps from the Phase 1.1 / UX follow-up:
+
+  1. **Dedicated error types** -- ``InvalidMoneyPrecisionError``
+     and ``InvalidMoneyAmountError`` (both subclass
+     ``ValueError`` for backward compat). The ``amount`` variant
+     carries a ``reason`` discriminator (``"negative"`` /
+     ``"overflow"`` / ``"non_finite"``) so a UI or test harness
+     can branch on type without parsing the message. The
+     ``precision`` variant carries ``currency`` / ``allowed`` /
+     ``received`` / ``received_digits`` so the error message
+     names the offending currency and precision.
+
+  2. **Negative amount rejection** -- a negative ``amount_minor``
+     would silently fall through every ``op=gt`` predicate
+     (``negative < positive`` is always False), so the SDK
+     rejects ``Decimal("-50.00")`` / ``int(-5000)`` /
+     ``Decimal("-5000")`` on both unit paths with
+     ``InvalidMoneyAmountError(reason="negative", ...)``. ``0``
+     is accepted (legitimate $0.00 refund).
+
+  3. **Sub-precision Decimal rejection** -- ``Decimal("1.234")``
+     against a USD ``allowed=2`` precision is now
+     ``InvalidMoneyPrecisionError(currency="USD", allowed=2,
+     received=3, received_digits="1.234")`` instead of a silent
+     round to ``1.23`` that drops the high-order digit the user
+     explicitly typed. ``float`` and ``Decimal`` are treated
+     symmetrically; ``int`` always rounds 0-digits.
+
+  4. **Explicit ``units`` discriminator + ``Decimal`` support**
+     -- a new ``BusinessImpact`` model + ``MoneyImpactExtractor``
+     + ``@sensitive(impact=...)`` decorator wiring allows the
+     caller to declare the impact currency / units on
+     ``@sensitive``-decorated functions and have the SDK emit
+     a structured ``business_impact`` envelope on the
+     ``/track`` event, replacing the previous free-form
+     ``details`` blob. ``Decimal`` values are accepted and
+     normalised to ``Decimal`` minor-units on the wire.
+
+Side fixes (covered by the same audit pass):
+
+  * ``/execute`` now handles ``require_approval`` correctly
+    and re-checks with the ``approval_id`` returned by the
+    backend (was dropping the approval handshake on
+    round-trips).
+  * Server's ``approval_timeout`` is clamped to ``[1, 3600]s``
+    on the SDK side as defence against a malformed /
+    overshooting backend that returns ``0`` or ``2147483647``
+    in the Разрыв 1c field.
+
+Public API change (additive only, backward-compatible):
+
+  * ``InvalidMoneyPrecisionError``, ``InvalidMoneyAmountError``
+    -- new ``ValueError`` subclasses with structured fields.
+  * ``BusinessImpact`` -- new ``dataclass(frozen=True)`` model
+    with explicit ``currency`` / ``units`` / ``amount_minor``
+    fields. ``details`` dict is still accepted (legacy path).
+  * ``@sensitive(impact=BusinessImpact(...))`` -- new
+    decorator kwarg. Existing ``@sensitive(details=...)`` /
+    ``@sensitive(amount_minor=..., currency=...)`` callers keep
+    working on the happy path (now routed through
+    ``BusinessImpact`` internally).
+
+Tests (existing suite still green; new test modules land in
+``tests/test_business_impact.py`` /
+``tests/test_units_discriminator.py`` /
+``tests/test_money_hardening.py`` /
+``tests/test_sensitive_extractor.py`` /
+``tests/test_approval_money_flow.py`` /
+``tests/test_execute_approval_flow.py``):
+
+  * 5 Definition-of-Done scenarios cover negative-amount
+    rejection, sub-precision Decimal rejection, overflow
+    rejection, non-finite rejection, ``0`` accepted.
+  * Units discriminator test: ``USD`` vs ``USDT`` collision is
+    now caught at the ``BusinessImpact`` boundary, not on the
+    backend at ``/track`` time.
+  * ``/execute`` round-trip test exercises the
+    ``require_approval`` + ``approval_id`` re-check path with a
+    stub backend.
+  * Server ``approval_timeout`` clamp test verifies
+    ``[1, 3600]s`` boundary.
+  * 5 contract tests cover the ``MoneyImpactExtractor`` path
+    end-to-end.
+
+Verification (local):
+
+  * ``pytest tests/test_money_hardening.py
+    tests/test_business_impact.py tests/test_units_discriminator.py
+    tests/test_sensitive_extractor.py
+    tests/test_approval_money_flow.py
+    tests/test_execute_approval_flow.py`` -- all new tests
+    pass; no regressions in the existing suite.
+  * ``ruff check src/ tests/`` -- All checks passed.
+  * ``mypy src/`` -- Success: no issues found in 34 source
+    files.
+
+No SDK_MIN_VERSION bump (legacy backends unaffected). No on-wire
+change (envelope shape preserved). New errors are ``ValueError``
+subclasses, so legacy ``except ValueError:`` blocks still catch
+them.
+
+---
+
 v3.27 / 0.13.13 (2026-07-21) — Разрыв 1c SDK sync.
 
 Backend commit ``0ad03b9`` (Разрыв 1c, gate hot-path trigger)

src/nullrun/decorators.py

@@ -919,13 +919,16 @@ def refund_customer(amount_cents: int, customer_id: str):
     if fn is None:
         def _attach_decorator(_fn: F) -> F:
             if impact is not None:
-                setattr(_fn, "_nullrun_extractor", impact)
+                # `setattr` keeps mypy happy without a TYPE_CHECKING
+                # forward-reference declaration; ruff B010 is a
+                # stylistic preference (no functional risk here).
+                setattr(_fn, "_nullrun_extractor", impact)  # noqa: B010
             return _do_sensitive_register(_fn)
         return _attach_decorator  # type: ignore[return-value]
 
     # Bare form: @sensitive.
     if impact is not None:
-        setattr(fn, "_nullrun_extractor", impact)
+        setattr(fn, "_nullrun_extractor", impact)  # noqa: B010
     return _do_sensitive_register(fn)
 
 

src/nullrun/extractor.py

@@ -158,18 +158,18 @@ def refund(amount: Decimal) -> ... # 50 = $50.00 (5000 cents)
 
 import functools
 import inspect
+from collections.abc import Callable
 from decimal import Decimal, InvalidOperation
-from typing import Any, Callable, Optional, Union
+from typing import Any, Optional, Union
 
 from nullrun.business_impact import (
-    BusinessImpact,
-    MoneyImpact,
     INFLOW,
     OUTFLOW,
+    BusinessImpact,
+    MoneyImpact,
     compute_action_digest,
 )
 
-
 # Unit discriminators for the typed impact payload.
 #
 # ``minor`` = the value is already in minor units (cents, pence,
@@ -521,7 +521,7 @@ def _check_business_cap(
 
 
 def _to_minor_units(
-    value: Union[int, Decimal], units: str, currency: str,
+    value: int | Decimal, units: str, currency: str,
     enforce_business_cap: bool = True,
 ) -> int:
     """Convert a Decimal-or-int value to integer minor units.
@@ -669,8 +669,8 @@ def __init__(
     def impact_for(
         self,
         fn: Callable[..., Any],
-        args: tuple,
-        kwargs: dict,
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
     ) -> BusinessImpact:
         """Bind the call and pull ``self.argument`` out of the bound args.
 
@@ -722,8 +722,8 @@ def impact_for(
 
 
 @functools.lru_cache(maxsize=128)
-def _cached_signature(fn_id: int) -> Optional[inspect.Signature]:
-    for obj in gc_get_objects():  # type: ignore[name-defined]
+def _cached_signature(fn_id: int) -> inspect.Signature | None:
+    for obj in gc_get_objects():
         if id(obj) == fn_id:
             try:
                 return inspect.signature(obj)
@@ -773,6 +773,6 @@ def compute_impact_digest(impact: BusinessImpact) -> str:
     return compute_action_digest(impact)
 
 
-def gc_get_objects():
+def gc_get_objects() -> list[Any]:
     import gc
     return gc.get_objects()