cleanlib-sdk 0.4.4__tar.gz → 0.4.6__tar.gz

cleanlib_sdk-0.4.6/CHANGELOG.md

@@ -0,0 +1,82 @@
+# cleanlib-sdk changelog
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.6] — 2026-06-05
+
+### Added
+
+- `cleanlib_sdk.verdict_to_envelope_v1(verdict)` — pure-function structural
+  adapter that converts the App's wire-shape `Verdict` to the canonical
+  customer-facing `VerdictEnvelopeV1` (returned as a `dict[str, Any]`
+  matching `VerdictEnvelopeV1Schema`). Second of four parity-locked
+  implementations across the SDK fleet (Rust: `cleanlib_client::verdict_to_envelope_v1`
+  shipped in v0.1.4; JS + Go to follow). Ratified at
+  `decisions/2026-06-05-cycle-14-cleanlib-48-envelope-shape-ratification.md`
+  (cleanlib monorepo).
+- Status/reason_code derivation table mirrors the Rust adapter byte-for-byte:
+  `VECTOR_VERDICT + CRITICAL → DENY + VERDICT_EXPLOITATION_CRITICAL`,
+  `+ HIGH → DENY + VERDICT_LOW_TRUST`,
+  `+ MEDIUM → WARN + VERDICT_ABANDONED`,
+  `DM_THRESHOLD_BLOCK + HIGH/CRITICAL → DENY + VERDICT_DENY_LIST`,
+  `+ MEDIUM → WARN + VERDICT_DENY_LIST`,
+  `ALLOWED_NO_FINDINGS / INSUFFICIENT_DATA / unknown → ALLOW + VERDICT_CLEAN`.
+  `stale_since_at` set overrides `reason_code` to `VERDICT_DEGRADED_STALE`
+  while preserving the status tier.
+- `rich_data` sub-object populated with `suggested_actions`, `similar_to`,
+  `evidence_gaps`, `previous_verdict`, `confidence`, `composite_score`,
+  `source`, `severity`, `staleness_reason` when present on the Verdict.
+- Enrich-cascade slots (`remediation`, `exploitability`, `availability`)
+  are left `None`; consumers populate them via `HttpEnrichClient` before
+  calling `derive_status` for the canonical (status, reason_code) decision.
+
+## [0.4.5] — 2026-06-04
+
+### Added
+
+- `Verdict.previous_verdict` field plus a new `PreviousVerdict` pydantic
+  model (`verdict_id`, `verdict`, `computed_at`, `diff`). Parity-ripple with
+  `sdk-go.PreviousVerdict`. The CleanLibrary App emits this field in its
+  `/v1/customer/verdicts/...` envelope when a prior verdict exists for the
+  same package version; previously sdk-py deserialized it as a no-op via
+  pydantic-default tolerance and customers lost the verdict-state-change
+  signal. `PreviousVerdict` is exported from the package root alongside
+  `Verdict`.
+
+## [0.4.4] — 2026-06-04
+
+### Fixed
+
+- `cleanlib_sdk.__version__` synchronized with the package manifest version.
+  Previously the in-code `__version__` reported `0.4.2` while the published
+  artifact was `0.4.3` — telemetry that relied on `__version__` for User-Agent
+  composition was under-reporting deployment penetration.
+- Wheel + sdist now include `CHANGELOG.md`. Customers running `pip download`
+  + tar inspection (or browsing the PyPI release files page) see the version
+  history alongside the package code.
+
+## [0.4.3] — 2026-06-03
+
+### Fixed
+
+- `pyproject.toml` `[project.urls]` table sanitized: `Homepage`,
+  `Documentation`, and `Bug Tracker` now point at `cleanlibrary.clnstrt.dev`
+  rather than the internal source-of-truth URLs that previously rendered on
+  the PyPI listing page.
+- `README.md` cross-references brand-clean: repo-internal links replaced with
+  the customer-facing `cleanlibrary.clnstrt.dev` documentation site and
+  cross-language SDK registry pages (crates.io, pkg.clnstrt.dev, npmjs.com).
+
+### Notes
+
+- No runtime API or wire-protocol changes; this is a metadata + docs ship.
+- Verified via `python -m build` against the resulting `cleanlib_sdk-0.4.3-py3-none-any.whl`
+  `METADATA` + `cleanlib_sdk-0.4.3.tar.gz` `PKG-INFO`: zero
+  internal-source URL references.
+
+## 0.4.2 — enrich verb cascade + F4 default-flip to cleanlib-enrich
+
+## 0.4.1 — per-domain HTTP client split (HttpRemediationClient) + schema/reason-codes mirror + DeriveStatus + Client @deprecated
+
+## 0.4.0 — verb cascade + rich-data

{cleanlib_sdk-0.4.4 → cleanlib_sdk-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cleanlib-sdk
-Version: 0.4.4
+Version: 0.4.6
 Summary: CleanLibrary Python SDK — HttpVerdictClient + HttpRemediationClient + HttpEnrichClient triad (sister-shape with @cleanstart/cleanlib-sdk v0.4.4)
 Project-URL: Homepage, https://cleanlibrary.clnstrt.dev
 Project-URL: Documentation, https://cleanlibrary.clnstrt.dev/docs/sdk-python

{cleanlib_sdk-0.4.4 → cleanlib_sdk-0.4.6}/cleanlib_sdk/__init__.py

@@ -92,6 +92,7 @@ from cleanlib_sdk.types import (
     PolicyPreviewResponse,
     PolicyPreviewResult,
     RecommendedVersion,
+    PreviousVerdict,
     RiskAcceptResponse,
     ScanResponse,
     ScanResult,
@@ -99,7 +100,9 @@ from cleanlib_sdk.types import (
     Verdict,
 )
 
-__version__ = "0.4.4"
+from cleanlib_sdk.verdict_to_envelope import verdict_to_envelope_v1
+
+__version__ = "0.4.6"
 
 __all__ = [
     # v0.4.2 per-domain HTTP client triad (primary API)
@@ -142,8 +145,11 @@ __all__ = [
     "AVAILABILITY_ENUM",
     "derive_status",
     "StatusResult",
+    # CLEANLIB-48 envelope-shape ratification (v0.4.6)
+    "verdict_to_envelope_v1",
     # cycle-6 v0.4.0 types
     "Verdict",
+    "PreviousVerdict",
     "Attestation",
     "SignedAttestation",
     "RecommendedVersion",

{cleanlib_sdk-0.4.4 → cleanlib_sdk-0.4.6}/cleanlib_sdk/types.py

@@ -110,6 +110,28 @@ class Verdict(BaseModel):
     # Cycle-6 9th field (App PR #105). Package-level vuln/risk summary.
     package_risk: Optional["PackageRisk"] = None
 
+    # v0.4.5 CLEANLIB-50: previous_verdict parity with sdk-go.PreviousVerdict.
+    # CleanLibrary App emits this when a prior verdict exists for the same
+    # (ecosystem, package, version); previously sdk-py deserialized it as a
+    # no-op via pydantic-default tolerance and customers lost the
+    # verdict-state-change signal.
+    previous_verdict: Optional["PreviousVerdict"] = None
+
+
+class PreviousVerdict(BaseModel):
+    """Prior-verdict comparison surfaced on the canonical Verdict envelope
+    when a prior verdict exists for the same package version. Sister-shape
+    with `cleanlib_sdk_go.PreviousVerdict` + `cleanlib_client::PreviousVerdict`
+    + `cleanlib_core::PreviousVerdict` in the App.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    verdict_id: Optional[str] = None
+    verdict: Optional[str] = None
+    computed_at: Optional[str] = None
+    diff: Optional[str] = None
+
 
 class RecommendedVersion(BaseModel):
     """Recommended upgrade target. Mirrors cleanlib_core::RecommendedVersion;

cleanlib_sdk-0.4.6/cleanlib_sdk/verdict_to_envelope.py

@@ -0,0 +1,156 @@
+"""verdict_to_envelope_v1 — Verdict (App wire) → VerdictEnvelopeV1 (canonical) adapter.
+
+Ratified at ``decisions/2026-06-05-cycle-14-cleanlib-48-envelope-shape-ratification.md``
+(in the cleanlib monorepo). Sister of:
+
+- ``cleanlib_client::verdict_to_envelope_v1`` (Rust)
+- ``verdictToEnvelopeV1`` (sdk-js, planned)
+- ``VerdictToEnvelopeV1`` (sdk-go, planned)
+
+All four implementations produce byte-identical output for the same input
+Verdict; this is verified by the ``cleanlib-contract-fixtures`` Verdict-to-
+envelope golden pack (planned, decision doc action D.1).
+
+The adapter is a PURE STRUCTURAL CONVERSION. The output envelope's
+``remediation`` / ``exploitability`` / ``availability`` slots are always
+``None``; consumers populate them via the ``HttpEnrichClient`` cascade
+before running ``derive_status`` for the canonical decision derivation.
+
+Status/reason_code mapping table (App's view; consumer may re-derive
+after enriching)::
+
+    verdict label         | severity        | status | reason_code
+    ----------------------|-----------------|--------|---------------------------------
+    VECTOR_VERDICT        | CRITICAL        | DENY   | VERDICT_EXPLOITATION_CRITICAL
+    VECTOR_VERDICT        | HIGH            | DENY   | VERDICT_LOW_TRUST
+    VECTOR_VERDICT        | MEDIUM          | WARN   | VERDICT_ABANDONED
+    VECTOR_VERDICT        | LOW / NONE      | ALLOW  | VERDICT_CLEAN
+    DM_THRESHOLD_BLOCK    | CRITICAL / HIGH | DENY   | VERDICT_DENY_LIST
+    DM_THRESHOLD_BLOCK    | MEDIUM          | WARN   | VERDICT_DENY_LIST
+    DM_THRESHOLD_BLOCK    | LOW / NONE      | ALLOW  | VERDICT_CLEAN
+    ALLOWED_NO_FINDINGS   | any             | ALLOW  | VERDICT_CLEAN
+    INSUFFICIENT_DATA     | any             | ALLOW  | VERDICT_CLEAN
+    (unknown label)       | any             | ALLOW  | VERDICT_CLEAN
+
+Freshness override: if ``verdict.stale_since_at`` is not ``None``, the
+``reason_code`` is overridden to ``VERDICT_DEGRADED_STALE`` (status tier
+preserved). Sister of the enrich-substrate freshness override applied by
+``derive_status`` after the enrich cascade lands.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cleanlib_sdk.types import Verdict
+
+
+def verdict_to_envelope_v1(verdict: Verdict) -> dict[str, Any]:
+    """Convert a wire-shape :class:`Verdict` to a :data:`VerdictEnvelopeV1` dict.
+
+    Returns the envelope as a plain ``dict[str, Any]`` matching the
+    ``VerdictEnvelopeV1Schema`` (sdk-js v0.4.1 source-of-truth schema). The
+    returned dict can be passed directly to :func:`derive_status` after
+    populating the enrich-cascade fields.
+    """
+    status, reason_code = _derive_initial_status_reason(verdict)
+
+    # `as_of` falls back: computed_at → data_freshness_at → "". Mirrors
+    # Rust adapter's `verdict_to_envelope_v1` behavior exactly.
+    as_of = _isoformat_or_empty(verdict.computed_at) or _isoformat_or_empty(
+        verdict.data_freshness_at
+    )
+
+    return {
+        "status": status,
+        "reason_code": reason_code,
+        "human_message": verdict.reasoning or "",
+        "as_of": as_of,
+        "rich_data": _build_rich_data(verdict),
+        "remediation": None,
+        "exploitability": None,
+        "availability": None,
+    }
+
+
+def _derive_initial_status_reason(verdict: Verdict) -> tuple[str, str]:
+    # The wire shape carries `verdict_label` (alias for ``verdict``) and
+    # ``severity`` as Optional strings. Normalize to upper-case so legacy
+    # lower-case fixtures don't misclassify.
+    label = (verdict.verdict_label or "").upper()
+    severity = (verdict.severity or "NONE").upper()
+
+    if label == "VECTOR_VERDICT":
+        if severity == "CRITICAL":
+            status, reason = "DENY", "VERDICT_EXPLOITATION_CRITICAL"
+        elif severity == "HIGH":
+            status, reason = "DENY", "VERDICT_LOW_TRUST"
+        elif severity == "MEDIUM":
+            status, reason = "WARN", "VERDICT_ABANDONED"
+        else:
+            status, reason = "ALLOW", "VERDICT_CLEAN"
+    elif label == "DM_THRESHOLD_BLOCK":
+        if severity in ("CRITICAL", "HIGH"):
+            status, reason = "DENY", "VERDICT_DENY_LIST"
+        elif severity == "MEDIUM":
+            status, reason = "WARN", "VERDICT_DENY_LIST"
+        else:
+            status, reason = "ALLOW", "VERDICT_CLEAN"
+    else:
+        # ALLOWED_NO_FINDINGS / INSUFFICIENT_DATA / unknown → ALLOW + CLEAN.
+        # Forward-compat: future App-side labels default to ALLOW so older
+        # SDKs don't break on schema additions.
+        status, reason = "ALLOW", "VERDICT_CLEAN"
+
+    if verdict.stale_since_at is not None:
+        # Sister of the enrich-substrate freshness override in
+        # derive_status: status tier preserved, reason_code overridden.
+        reason = "VERDICT_DEGRADED_STALE"
+    return status, reason
+
+
+def _build_rich_data(verdict: Verdict) -> dict[str, Any]:
+    """Build the envelope's ``rich_data`` sub-object from the wire-shape
+    Verdict's rich fields. Mirrors the Rust adapter's `build_rich_data`."""
+    rich: dict[str, Any] = {}
+    if verdict.suggested_actions:
+        rich["suggested_actions"] = list(verdict.suggested_actions)
+    if verdict.similar_to:
+        rich["similar_to"] = list(verdict.similar_to)
+    if verdict.evidence_gaps:
+        rich["evidence_gaps"] = list(verdict.evidence_gaps)
+    if verdict.previous_verdict is not None:
+        pv = verdict.previous_verdict
+        rich["previous_verdict"] = {
+            "verdict_id": pv.verdict_id or "",
+            "verdict": pv.verdict or "",
+            "computed_at": pv.computed_at or "",
+            "diff": pv.diff or "",
+        }
+    rich["confidence"] = verdict.confidence if verdict.confidence is not None else 0.0
+    rich["composite_score"] = (
+        verdict.composite_score if verdict.composite_score is not None else 0
+    )
+    if verdict.source:
+        rich["source"] = verdict.source
+    if verdict.severity:
+        rich["severity"] = verdict.severity
+    if verdict.staleness_reason:
+        rich["staleness_reason"] = verdict.staleness_reason
+    return rich
+
+
+def _isoformat_or_empty(dt: Any) -> str:
+    """Render a datetime or ISO string as a UTC ISO string with Z suffix."""
+    if dt is None:
+        return ""
+    if isinstance(dt, str):
+        return dt
+    # pydantic datetime — use isoformat; convert +00:00 → Z for wire-parity
+    # with the Rust adapter which emits whatever the App's serializer
+    # produced.
+    try:
+        s = dt.isoformat()
+    except Exception:
+        return str(dt)
+    return s.replace("+00:00", "Z")

{cleanlib_sdk-0.4.4 → cleanlib_sdk-0.4.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cleanlib-sdk"
-version = "0.4.4"
+version = "0.4.6"
 description = "CleanLibrary Python SDK — HttpVerdictClient + HttpRemediationClient + HttpEnrichClient triad (sister-shape with @cleanstart/cleanlib-sdk v0.4.4)"
 readme = "README.md"
 requires-python = ">=3.10"

cleanlib_sdk-0.4.4/CHANGELOG.md

@@ -1,41 +0,0 @@
-# cleanlib-sdk changelog
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [0.4.4] — 2026-06-04
-
-### Fixed
-
-- `cleanlib_sdk.__version__` synchronized with the package manifest version.
-  Previously the in-code `__version__` reported `0.4.2` while the published
-  artifact was `0.4.3` — telemetry that relied on `__version__` for User-Agent
-  composition was under-reporting deployment penetration.
-- Wheel + sdist now include `CHANGELOG.md`. Customers running `pip download`
-  + tar inspection (or browsing the PyPI release files page) see the version
-  history alongside the package code.
-
-## [0.4.3] — 2026-06-03
-
-### Fixed
-
-- `pyproject.toml` `[project.urls]` table sanitized: `Homepage`,
-  `Documentation`, and `Bug Tracker` now point at `cleanlibrary.clnstrt.dev`
-  rather than the internal source-of-truth URLs that previously rendered on
-  the PyPI listing page.
-- `README.md` cross-references brand-clean: repo-internal links replaced with
-  the customer-facing `cleanlibrary.clnstrt.dev` documentation site and
-  cross-language SDK registry pages (crates.io, pkg.clnstrt.dev, npmjs.com).
-
-### Notes
-
-- No runtime API or wire-protocol changes; this is a metadata + docs ship.
-- Verified via `python -m build` against the resulting `cleanlib_sdk-0.4.3-py3-none-any.whl`
-  `METADATA` + `cleanlib_sdk-0.4.3.tar.gz` `PKG-INFO`: zero
-  internal-source URL references.
-
-## 0.4.2 — enrich verb cascade + F4 default-flip to cleanlib-enrich
-
-## 0.4.1 — per-domain HTTP client split (HttpRemediationClient) + schema/reason-codes mirror + DeriveStatus + Client @deprecated
-
-## 0.4.0 — verb cascade + rich-data