solvapay-python 0.9.0__tar.gz → 0.9.2__tar.gz

{solvapay_python-0.9.0 → solvapay_python-0.9.2}/.github/workflows/ci.yml

@@ -4,8 +4,32 @@ on:
   push:
     branches: [main]
   pull_request:
+  schedule:
+    - cron: "0 7 * * *"  # nightly security sweep
 
 jobs:
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv python install 3.12
+      - run: uv sync --all-extras --dev
+      - name: bandit (high-severity, high-confidence only)
+        run: uv run bandit -r src/ -lll
+      - name: osv-scanner (lockfile vuln DB cross-check)
+        # PYSEC-2026-196: vuln in the GitHub runner's bundled pip, not in any
+        # solvapay-python dependency (pip is pulled into uv.lock transitively
+        # by build tooling). Ignore — runner image hygiene is GitHub's job.
+        run: |
+          docker run --rm -v "${PWD}:/src" -w /src \
+            ghcr.io/google/osv-scanner:latest \
+            scan source --lockfile=/src/uv.lock \
+            --config=/src/.osv-scanner.toml
+
+
   test:
     strategy:
       matrix:
@@ -25,8 +49,10 @@ jobs:
             python-version: "3.12"
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v3
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       - name: Set Python ${{ matrix.python-version }}
@@ -40,10 +66,14 @@ jobs:
       - run: uv run lint-imports --config tools/importlinter.cfg
       - run: uv run python tools/lint_invariants.py
       - name: pip-audit
-        run: uv run pip-audit
+        # PYSEC-2026-196: vuln in the GitHub runner's bundled pip (26.1.1, fixed in 26.1.2).
+        # Not a vuln in any solvapay-python dependency — runner-side hygiene only.
+        run: uv run pip-audit --ignore-vuln PYSEC-2026-196
       - name: Check changelog fragment on PRs touching src/
         if: github.event_name == 'pull_request'
+        shell: bash
         run: |
+          git fetch origin ${{ github.base_ref }}
           changed=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
           if echo "$changed" | grep -q "^src/"; then
             if ! echo "$changed" | grep -q "^changelog.d/"; then

{solvapay_python-0.9.0 → solvapay_python-0.9.2}/.github/workflows/contract.yml

@@ -9,8 +9,8 @@ jobs:
   contract:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v3
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       - run: uv sync --all-extras --dev

{solvapay_python-0.9.0 → solvapay_python-0.9.2}/.github/workflows/docs.yml

@@ -12,8 +12,8 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v3
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       - run: uv sync --group docs

solvapay_python-0.9.2/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: publish
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - name: Generate CycloneDX SBOM
+        run: |
+          # Resolve runtime + all-extras deps from the lockfile and emit a CycloneDX SBOM.
+          uv export --no-dev --all-extras --no-emit-project --format requirements-txt > /tmp/sbom-requirements.txt
+          uv tool run --from cyclonedx-bom cyclonedx-py requirements \
+            --pyproject pyproject.toml \
+            --of JSON --sv 1.6 \
+            -o sbom.cdx.json \
+            /tmp/sbom-requirements.txt
+      - name: Publish to PyPI (Sigstore-signed via trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true
+      - name: Attach SBOM to GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "${GITHUB_REF_NAME}" sbom.cdx.json --clobber

{solvapay_python-0.9.0 → solvapay_python-0.9.2}/.gitignore

@@ -13,3 +13,4 @@ htmlcov/
 .env.local
 *.egg
 .DS_Store
+site/

solvapay_python-0.9.2/.osv-scanner.toml

@@ -0,0 +1,6 @@
+[[IgnoredVulns]]
+id = "PYSEC-2026-196"
+# pip 26.1.1 vuln, fixed in 26.1.2. Pip lands in uv.lock transitively via build
+# tooling on the GitHub runner — not a solvapay-python runtime/optional dep.
+# Runner image hygiene is GitHub's responsibility.
+reason = "Runner-side pip — not a project dependency"

{solvapay_python-0.9.0 → solvapay_python-0.9.2}/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## [0.9.2] — 2026-06-06
+
+### Features
+
+- ``solvapay.sign_webhook`` promoted to top-level namespace (alongside ``verify_webhook``), closing the inconsistency flagged in v0.9.0 deviation #3. The existing ``solvapay.webhooks.sign_webhook`` path is unchanged.
+
+  Cold-import baseline harness at ``tests/test_cold_import.py``: measures ``python -X importtime`` cumulative time and asserts within 1.5x of a committed baseline. The hard <200 ms CI gate is a v1.0 feature (HLD §V1.20).
+
+  Microbenchmark harness at ``tests/benchmarks/``: measures ``SolvaPay()`` construction, ``verify_webhook`` per-call, and ``from_payload`` derivation. Opt-in via ``solvapay[bench]`` extra. Excluded from default pytest run.
+
+### Documentation
+
+- ``docs/troubleshooting.md``: top-10 user errors with symptom, cause, and fix. Covers missing env vars, async-in-sync deadlock, missing extras, contract test skips, Windows paths, deprecation warnings, paywall checkout URL, ``verify_webhook`` errors, mypy mock patterns, and PyPI dist-name confusion.
+
+  ``docs/architecture/cold-start.md``: explains the ``python -X importtime`` baseline harness, PEP 562 lazy adapter import pattern, and the v1.0 <150 ms cold-start budget (HLD §V1.20).
+
+### Performance
+
+- PEP 562 lazy adapter imports: bare ``import solvapay`` no longer loads ``fastmcp``, ``langchain-core``, or ``fastapi``. Framework adapter modules load on first attribute access only. ``solvapay.adapters`` is accessible via ``__getattr__`` and appears in ``dir(solvapay)``.
+
+
+---
+
+## [0.9.1] — 2026-06-05
+
+Security & supply-chain quality patch (no public API change).
+
+### Features
+
+- ``publish.yml``: PyPI uploads now ship PEP 740 attestations (Sigstore-backed via OIDC trusted publishing) and attach a CycloneDX SBOM (``sbom.cdx.json``) to each GitHub release.
+- CI: new ``security`` job runs ``bandit -r src/ -lll`` (high-confidence high-severity only) and ``osv-scanner --lockfile=uv.lock`` as a cross-DB check against ``pip-audit``. Runs on PR and nightly cron.
+- ``tests/test_redaction.py``: property-based test with Hypothesis (100 derandomized cases) drives random API keys, hex tokens, and webhook secrets through the HTTP transport and asserts the secret never appears in ``caplog.text`` at any log level.
+- ``tests/test_webhook_timing.py``: smoke test that compares ``verify_webhook`` perf-counter distributions for perfect-match vs near-miss signatures, regressing if someone swaps ``hmac.compare_digest`` for ``==``.
+
+### Bug Fixes
+
+- ``pyproject.toml``: tighten ``httpx`` to ``<0.29`` (closes deviation: was unbounded). FastAPI extra remains unbounded by design — documented in-file.
+
+### Documentation
+
+- ``SECURITY.md``: explicit PCI-scope section — the SDK never transmits raw cardholder data; tokenization is server-side.
+
+---
+
 ## 0.9.0 — 2026-05-23
 
 Production polish + C1 adversarial-review closure. API-version pinning, idempotency TTL, webhook secret rotation, ASGI adapter, retry/recording transports, contract tests, lint automation, doc site, supply-chain hardening.

{solvapay_python-0.9.0 → solvapay_python-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solvapay-python
-Version: 0.9.0
+Version: 0.9.2
 Summary: Community Python SDK for SolvaPay (agent-native payment rails)
 Project-URL: Homepage, https://github.com/dhruv-sanan/solvapay-python
 Project-URL: Issues, https://github.com/dhruv-sanan/solvapay-python/issues
@@ -21,15 +21,17 @@ Classifier: Topic :: Office/Business :: Financial
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: httpx>=0.27
-Requires-Dist: pydantic<2.13,>=2.6
+Requires-Dist: httpx<0.29,>=0.27
+Requires-Dist: pydantic<2.14,>=2.6
 Provides-Extra: asgi
+Provides-Extra: bench
+Requires-Dist: pytest-benchmark<6,>=4.0; extra == 'bench'
 Provides-Extra: fastapi
 Requires-Dist: fastapi>=0.110; extra == 'fastapi'
 Provides-Extra: langchain
-Requires-Dist: langchain-core<0.4,>=0.3; extra == 'langchain'
+Requires-Dist: langchain-core<1.5,>=0.3; extra == 'langchain'
 Provides-Extra: mcp
-Requires-Dist: fastmcp<0.5,>=0.4; extra == 'mcp'
+Requires-Dist: fastmcp<4,>=3.2.0; extra == 'mcp'
 Provides-Extra: retry
 Requires-Dist: tenacity<10,>=8.2; extra == 'retry'
 Description-Content-Type: text/markdown
@@ -138,16 +140,23 @@ if limits.within_limits:
 
 ## Idempotency
 
-All mutating ops accept `idempotency_key`. Use `solvapay.idempotency.from_payload` to derive deterministic keys from request content:
+All mutating ops accept `idempotency_key`. Use `solvapay.idempotency.from_payload` to derive deterministic keys:
 
 ```python
 from solvapay.idempotency import from_payload
 
+# Default: key includes UTC date — rolls at midnight, bounds replay past server TTL
 key = from_payload("track_usage", customer_ref, product_ref, "requests", units)
 sv.usage.track(..., idempotency_key=key)   # retry-safe
+
+# Hourly bucket (high-frequency ops)
+key = from_payload("charge", customer_ref, time_bucket="hour")
+
+# Pure payload hash — caller manages TTL externally
+key = from_payload("idempotent_op", ref, time_bucket=None)
 ```
 
-Retried POSTs **must reuse the same key**. Key should change only when the logical request changes.
+Retried POSTs **must reuse the same key**. A bucket roll (midnight / hour boundary) produces a new key — the server treats it as a new request.
 
 ---
 
@@ -174,7 +183,7 @@ except SolvaPayError as e:
     ...  # catch-all
 ```
 
-No built-in retries by design. Layer `tenacity` manually. `solvapay[retry]` RetryTransport ships in v0.9.
+No built-in retries by default. `solvapay[retry]` ships `RetryTransport` — exponential backoff with jitter, 3 attempts, respects `OpSpec.retry_safety` (won't retry non-idempotent ops without an idempotency key). Or layer `tenacity` manually.
 
 ---
 
@@ -193,6 +202,30 @@ pipeline = WebhookPipeline(
 envelope = pipeline.process(body=request.body, signature=request.headers["sv-signature"])
 ```
 
+**Secret rotation** — pass multiple secrets; primary tried first, secondary on mismatch:
+
+```python
+pipeline = WebhookPipeline(["whsec_new...", "whsec_old..."])
+```
+
+**Sign a webhook** (testing / outbound fanout) — available at the top level since v0.9.2:
+
+```python
+from solvapay import sign_webhook          # top-level (v0.9.2+)
+# from solvapay.webhooks import sign_webhook  # subpackage path also works
+
+header = sign_webhook(body=b'{"type":"purchase.created"}', secret="whsec_...")
+# → "t=1716470000,v1=abc123..."
+```
+
+**ASGI adapter** — mount directly in FastAPI / Starlette / Litestar:
+
+```python
+from solvapay.adapters.asgi import webhook_app
+
+app.mount("/webhook", webhook_app(pipeline, on_event=handle))
+```
+
 **Typed events** — discriminated union over 13 event types:
 
 ```python
@@ -279,6 +312,9 @@ pip install solvapay-python                   # core
 pip install 'solvapay-python[mcp]'            # + FastMCP adapter (FastMCP ≥0.4)
 pip install 'solvapay-python[langchain]'      # + LangChain adapter (langchain-core ≥0.3)
 pip install 'solvapay-python[fastapi]'        # + FastAPI webhook router
+pip install 'solvapay-python[asgi]'           # + raw ASGI webhook adapter (no extra deps)
+pip install 'solvapay-python[retry]'          # + RetryTransport (tenacity)
+pip install 'solvapay-python[bench]'          # + pytest-benchmark (dev/perf testing)
 ```
 
 ## Environment variables
@@ -302,17 +338,43 @@ pip install 'solvapay-python[fastapi]'        # + FastAPI webhook router
 
 ---
 
+## API version pinning
+
+Pin the API version your code was written against — prevents silent breakage when the server evolves:
+
+```python
+sv = SolvaPay(api_version="2026-05-22")   # sends Solvapay-Version header
+sv = SolvaPay(api_version=None)            # omit header (use server default)
+```
+
+Default is `"2026-05-22"` (v0.9 ship date). Bump only on major SDK versions.
+
+---
+
 ## Roadmap
 
 | Version | Theme |
 |---------|-------|
 | v0.8 ✅ | V1 architecture spine — Transport kernel, OpSpec registry, paywall/webhook packages, `@payable_tool`, stability manifest, layer DAG CI gate |
-| v0.9 | Production polish — API-version pinning, idempotency TTL, `RetryTransport`, `RecordingTransport`, contract tests, lint automation, doc site (MkDocs Material), supply-chain hygiene |
-| v1.0 | Gated on founder signal — OpenAPI-generated models, full secret rotation, production hardening |
+| v0.9 ✅ | Production polish — API-version pinning, idempotency TTL, `RetryTransport`, `RecordingTransport`, ASGI adapter, secret rotation, `sign_webhook`, contract tests, lint automation, MkDocs site, supply-chain hygiene |
+| v0.9.1 ✅ | Security & supply-chain quality — PyPI attestations (PEP 740 / Sigstore), CycloneDX SBOM on releases, `bandit` + `osv-scanner` CI, Hypothesis-driven secret-redaction property tests, constant-time `verify_webhook` smoke test, explicit PCI-scope statement |
+| v0.9.2 ✅ | Performance & stability quality — cold-import baseline harness, PEP 562 lazy adapter imports, `solvapay.sign_webhook` top-level re-export, microbenchmark harness (`solvapay[bench]`), troubleshooting docs |
+| v1.0 | Gated on founder signal — OpenAPI-generated models, WSGI/Lambda adapters, V2 planning |
 
 ---
 
 ## Status
 
-**v0.8.0** — V1 architecture spine + AI-agent moat. `mypy --strict` clean (43 files). 261 tests. 89% line coverage.  
+**v0.9.2** — Performance & stability quality patch. Cold-import baseline harness (`tests/test_cold_import.py`, 1.5x regression gate). PEP 562 lazy adapter imports — bare `import solvapay` no longer loads framework adapter modules. `solvapay.sign_webhook` promoted to top-level (alongside `verify_webhook`). Microbenchmark harness under `tests/benchmarks/` (opt-in `solvapay[bench]`). New docs: `docs/troubleshooting.md` (top-10 errors) and `docs/architecture/cold-start.md`. 305 tests. 87% line coverage. `mypy --strict` clean (45 files).
+
+**v0.9.1** — Security & supply-chain quality patch. PyPI uploads now carry PEP 740 attestations (Sigstore-backed via OIDC trusted publishing); each GitHub release ships a CycloneDX SBOM (`sbom.cdx.json`). `mypy --strict` clean (45 files). 302 tests. 87% line / 85% branch coverage.
+
+**Supply chain & security posture:**
+- PyPI trusted publishing with PEP 740 attestations (Sigstore)
+- CycloneDX 1.6 SBOM attached to every release
+- CI runs `bandit -r src/ -lll`, `osv-scanner --lockfile=uv.lock`, and `pip-audit` (cross-DB vuln check) on PR and nightly cron
+- Constant-time HMAC comparison (`hmac.compare_digest`) regression-smoked
+- Hypothesis-driven property tests assert no API key, hex token, or webhook secret leaks into log output at any level
+- Tightened upper bounds on volatile deps (`httpx<0.29`, `pydantic<2.14`, `langchain-core<1.5`)
+
 Community SDK, not official. Proposal: [solvapay/solvapay-sdk#187](https://github.com/solvapay/solvapay-sdk/issues/187).

{solvapay_python-0.9.0 → solvapay_python-0.9.2}/README.md

@@ -102,16 +102,23 @@ if limits.within_limits:
 
 ## Idempotency
 
-All mutating ops accept `idempotency_key`. Use `solvapay.idempotency.from_payload` to derive deterministic keys from request content:
+All mutating ops accept `idempotency_key`. Use `solvapay.idempotency.from_payload` to derive deterministic keys:
 
 ```python
 from solvapay.idempotency import from_payload
 
+# Default: key includes UTC date — rolls at midnight, bounds replay past server TTL
 key = from_payload("track_usage", customer_ref, product_ref, "requests", units)
 sv.usage.track(..., idempotency_key=key)   # retry-safe
+
+# Hourly bucket (high-frequency ops)
+key = from_payload("charge", customer_ref, time_bucket="hour")
+
+# Pure payload hash — caller manages TTL externally
+key = from_payload("idempotent_op", ref, time_bucket=None)
 ```
 
-Retried POSTs **must reuse the same key**. Key should change only when the logical request changes.
+Retried POSTs **must reuse the same key**. A bucket roll (midnight / hour boundary) produces a new key — the server treats it as a new request.
 
 ---
 
@@ -138,7 +145,7 @@ except SolvaPayError as e:
     ...  # catch-all
 ```
 
-No built-in retries by design. Layer `tenacity` manually. `solvapay[retry]` RetryTransport ships in v0.9.
+No built-in retries by default. `solvapay[retry]` ships `RetryTransport` — exponential backoff with jitter, 3 attempts, respects `OpSpec.retry_safety` (won't retry non-idempotent ops without an idempotency key). Or layer `tenacity` manually.
 
 ---
 
@@ -157,6 +164,30 @@ pipeline = WebhookPipeline(
 envelope = pipeline.process(body=request.body, signature=request.headers["sv-signature"])
 ```
 
+**Secret rotation** — pass multiple secrets; primary tried first, secondary on mismatch:
+
+```python
+pipeline = WebhookPipeline(["whsec_new...", "whsec_old..."])
+```
+
+**Sign a webhook** (testing / outbound fanout) — available at the top level since v0.9.2:
+
+```python
+from solvapay import sign_webhook          # top-level (v0.9.2+)
+# from solvapay.webhooks import sign_webhook  # subpackage path also works
+
+header = sign_webhook(body=b'{"type":"purchase.created"}', secret="whsec_...")
+# → "t=1716470000,v1=abc123..."
+```
+
+**ASGI adapter** — mount directly in FastAPI / Starlette / Litestar:
+
+```python
+from solvapay.adapters.asgi import webhook_app
+
+app.mount("/webhook", webhook_app(pipeline, on_event=handle))
+```
+
 **Typed events** — discriminated union over 13 event types:
 
 ```python
@@ -243,6 +274,9 @@ pip install solvapay-python                   # core
 pip install 'solvapay-python[mcp]'            # + FastMCP adapter (FastMCP ≥0.4)
 pip install 'solvapay-python[langchain]'      # + LangChain adapter (langchain-core ≥0.3)
 pip install 'solvapay-python[fastapi]'        # + FastAPI webhook router
+pip install 'solvapay-python[asgi]'           # + raw ASGI webhook adapter (no extra deps)
+pip install 'solvapay-python[retry]'          # + RetryTransport (tenacity)
+pip install 'solvapay-python[bench]'          # + pytest-benchmark (dev/perf testing)
 ```
 
 ## Environment variables
@@ -266,17 +300,43 @@ pip install 'solvapay-python[fastapi]'        # + FastAPI webhook router
 
 ---
 
+## API version pinning
+
+Pin the API version your code was written against — prevents silent breakage when the server evolves:
+
+```python
+sv = SolvaPay(api_version="2026-05-22")   # sends Solvapay-Version header
+sv = SolvaPay(api_version=None)            # omit header (use server default)
+```
+
+Default is `"2026-05-22"` (v0.9 ship date). Bump only on major SDK versions.
+
+---
+
 ## Roadmap
 
 | Version | Theme |
 |---------|-------|
 | v0.8 ✅ | V1 architecture spine — Transport kernel, OpSpec registry, paywall/webhook packages, `@payable_tool`, stability manifest, layer DAG CI gate |
-| v0.9 | Production polish — API-version pinning, idempotency TTL, `RetryTransport`, `RecordingTransport`, contract tests, lint automation, doc site (MkDocs Material), supply-chain hygiene |
-| v1.0 | Gated on founder signal — OpenAPI-generated models, full secret rotation, production hardening |
+| v0.9 ✅ | Production polish — API-version pinning, idempotency TTL, `RetryTransport`, `RecordingTransport`, ASGI adapter, secret rotation, `sign_webhook`, contract tests, lint automation, MkDocs site, supply-chain hygiene |
+| v0.9.1 ✅ | Security & supply-chain quality — PyPI attestations (PEP 740 / Sigstore), CycloneDX SBOM on releases, `bandit` + `osv-scanner` CI, Hypothesis-driven secret-redaction property tests, constant-time `verify_webhook` smoke test, explicit PCI-scope statement |
+| v0.9.2 ✅ | Performance & stability quality — cold-import baseline harness, PEP 562 lazy adapter imports, `solvapay.sign_webhook` top-level re-export, microbenchmark harness (`solvapay[bench]`), troubleshooting docs |
+| v1.0 | Gated on founder signal — OpenAPI-generated models, WSGI/Lambda adapters, V2 planning |
 
 ---
 
 ## Status
 
-**v0.8.0** — V1 architecture spine + AI-agent moat. `mypy --strict` clean (43 files). 261 tests. 89% line coverage.  
+**v0.9.2** — Performance & stability quality patch. Cold-import baseline harness (`tests/test_cold_import.py`, 1.5x regression gate). PEP 562 lazy adapter imports — bare `import solvapay` no longer loads framework adapter modules. `solvapay.sign_webhook` promoted to top-level (alongside `verify_webhook`). Microbenchmark harness under `tests/benchmarks/` (opt-in `solvapay[bench]`). New docs: `docs/troubleshooting.md` (top-10 errors) and `docs/architecture/cold-start.md`. 305 tests. 87% line coverage. `mypy --strict` clean (45 files).
+
+**v0.9.1** — Security & supply-chain quality patch. PyPI uploads now carry PEP 740 attestations (Sigstore-backed via OIDC trusted publishing); each GitHub release ships a CycloneDX SBOM (`sbom.cdx.json`). `mypy --strict` clean (45 files). 302 tests. 87% line / 85% branch coverage.
+
+**Supply chain & security posture:**
+- PyPI trusted publishing with PEP 740 attestations (Sigstore)
+- CycloneDX 1.6 SBOM attached to every release
+- CI runs `bandit -r src/ -lll`, `osv-scanner --lockfile=uv.lock`, and `pip-audit` (cross-DB vuln check) on PR and nightly cron
+- Constant-time HMAC comparison (`hmac.compare_digest`) regression-smoked
+- Hypothesis-driven property tests assert no API key, hex token, or webhook secret leaks into log output at any level
+- Tightened upper bounds on volatile deps (`httpx<0.29`, `pydantic<2.14`, `langchain-core<1.5`)
+
 Community SDK, not official. Proposal: [solvapay/solvapay-sdk#187](https://github.com/solvapay/solvapay-sdk/issues/187).

{solvapay_python-0.9.0 → solvapay_python-0.9.2}/SECURITY.md

@@ -13,8 +13,17 @@ This is a **community** Python SDK. It is not an official SolvaPay product.
 - SolvaPay server-side vulnerabilities
 - Issues requiring a SolvaPay account to reproduce
 
-**PCI scope:** The SDK never transmits raw cardholder data (PAN, CVV, expiry).
-It only exchanges SolvaPay API keys and customer references over HTTPS.
+## PCI Scope
+
+The SDK **never transmits raw cardholder data (PAN, CVV, expiry, track data)**.
+All tokenization happens **server-side** at the SolvaPay API; the SDK only
+exchanges SolvaPay API keys, customer references, and tokenized identifiers
+over HTTPS. Integrators using this SDK do not bring PAN data into their
+own application scope through it.
+
+If you discover any code path that would cause raw cardholder data to traverse
+the SDK boundary, treat it as a high-severity vulnerability and report it via
+the channel below.
 
 ## Reporting a Vulnerability
 
@@ -25,6 +34,9 @@ Please include:
 - Steps to reproduce
 - Any proof-of-concept code (privately)
 
+Encrypt sensitive payloads with the maintainer's public key on request.
+Do **not** open public GitHub issues for suspected vulnerabilities.
+
 **Response SLA:** Best-effort; typically within 7 days.
 **Disclosure policy:** 90-day coordinated disclosure. Public CVE filed only for confirmed SDK bugs.
 
@@ -32,5 +44,6 @@ Please include:
 
 | Version | Supported |
 |---------|-----------|
+| 0.9.x   | Yes       |
 | 0.8.x   | Yes       |
 | < 0.8   | No — upgrade recommended |

solvapay_python-0.9.2/docs/architecture/cold-start.md

@@ -0,0 +1,70 @@
+# Cold-Start Performance
+
+## What we measure
+
+`python -X importtime -c "import solvapay"` prints a line per imported module:
+
+```
+import time:    <self_µs> | <cumulative_µs> | <module_name>
+```
+
+The `cumulative_µs` column for the root `solvapay` module is the total cold-import cost — the number we track.
+
+## The baseline harness (`tests/test_cold_import.py`)
+
+Introduced in v0.9.2, `tests/test_cold_import.py` runs the above command via `subprocess` and:
+
+1. **First run** — writes `tests/_baselines/cold_import.json` with the measured value.
+2. **Subsequent runs** — asserts the current measurement is within **1.5×** of the baseline.
+
+The 1.5× regression factor is intentionally loose — it catches gross regressions (importing a new heavy dependency eagerly) without failing on normal M-series vs CI machine variance.
+
+The committed baseline is re-measured and updated whenever a structural change affects import cost (e.g. lazy adapter imports in v0.9.2).
+
+### Current baseline
+
+| Version | M-series (macOS) | What changed |
+|---------|-----------------|--------------|
+| v0.9.1  | ~88 ms          | Initial measurement |
+| v0.9.2  | ~100 ms         | PEP 562 `__getattr__` + `__dir__` added; adapters lazy |
+
+## PEP 562 lazy adapter imports
+
+Adapter modules (`solvapay.adapters.mcp`, `solvapay.adapters.langchain`, etc.) depend on optional heavy packages — `fastmcp`, `langchain-core`, `fastapi`. These are only installed when the user runs `pip install solvapay-python[mcp]` etc.
+
+Before v0.9.2, accessing `solvapay.adapters` required an explicit subpackage import. In v0.9.2, `solvapay/__init__.py` defines a PEP 562 `__getattr__` that loads `solvapay.adapters` lazily on first attribute access:
+
+```python
+# In solvapay/__init__.py
+_LAZY_MODULES = {"adapters": "solvapay.adapters"}
+
+def __getattr__(name: str) -> object:
+    if name in _LAZY_MODULES:
+        import importlib
+        mod = importlib.import_module(_LAZY_MODULES[name])
+        globals()[name] = mod  # cache for subsequent accesses
+        return mod
+    raise AttributeError(f"module 'solvapay' has no attribute {name!r}")
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_LAZY_MODULES))
+```
+
+This ensures:
+- `import solvapay` — **zero adapter cost** regardless of which extras are installed.
+- `solvapay.adapters` — triggers a single load on first access, cached thereafter.
+- `from solvapay.adapters import mcp` — works via Python's normal subpackage import path (unaffected by `__getattr__`).
+- `dir(solvapay)` — lists `"adapters"` per PEP 562 convention.
+
+## v1.0 hard budget (HLD §V1.20)
+
+v0.9.2 ships **measurement only**. The hard gate is a v1.0 feature:
+
+| Environment | Budget |
+|-------------|--------|
+| M-series Mac | < 150 ms |
+| x86 CI | < 300 ms |
+
+v1.0 achieves this primarily via **`@cached_property` lazy namespace materialization** — `SolvaPay.__init__` will no longer eagerly construct `customers`, `checkout`, `limits`, etc. Each namespace is constructed on first access (`sv.customers.ensure(...)`) and cached as an instance attribute. This eliminates the linear startup cost as V2/V3 expand the namespace count.
+
+See `HLD.md §V1.3 RN1-v2` and `§V1.20` for the full contract.