manithy-sdk 0.1.0__tar.gz

manithy_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: manithy-sdk
+Version: 0.1.0
+Summary: Manithy SDK — Authority-Grade Audit Capture (Zero Dependencies)
+License: Proprietary
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+
+# Manithy SDK (Python)
+
+**Authority-Grade Audit Capture — Zero Dependencies**
+
+Manithy captures tamper-evident audit proofs at the application layer.
+Each proof is a **J01 CommitBoundaryEvent** — a structured record that
+marks the exact t-1 boundary before an irreversible action and freezes
+only facts already resolved in the execution context.
+
+No lookups. No inference. No enrichment.
+
+## Design Constraints
+
+| Constraint | Guarantee |
+|---|---|
+| **Zero Network I/O** | The SDK never opens sockets or makes HTTP calls. |
+| **Determinism** | Identical inputs always yield identical commit-IDs. |
+| **Fail-Closed** | Internal errors are silently swallowed — the host app never crashes. |
+| **Zero Dependencies** | Only the Python standard library is used at runtime. |
+| **Epistemic Honesty** | The `availability` block declares what was knowable at t-1. Unknown facts must never appear in `observed`. |
+
+## Installation
+
+```bash
+pip install manithy-sdk
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/VooYee/manithy-sdk.git
+cd manithy-sdk
+pip install .
+```
+
+## Quick Start
+
+```python
+from manithy import ManithySDK
+
+sdk = ManithySDK()
+
+result = sdk.capture(
+    boundary_kind="REFUND_COMMIT_T_MINUS_1",
+    boundary_seq=1,
+    same_thread=True,
+    observed={
+        "action_kind": "REFUND",
+        "amount_minor": 12900,
+        "currency": "EUR",
+        "refund_mode": "FULL",
+        "order_channel": "WEB",
+        "payment_method": "CARD",
+        "merchant_region": "EU",
+        "customer_present": False,
+        "operator_initiated": False,
+    },
+    availability={
+        "psp_refund_capability_known": True,
+        "original_payment_state_known": True,
+        "chargeback_state_known": False,
+    },
+    reentrancy_guard="SINGLE_CAPTURE_ENFORCED",
+)
+
+print(result)
+# {"status": "CAPTURED", "id": "a3f8c9..."}
+```
+
+Output (stdout):
+
+```
+MANITHY_PROOF::{"schema_id":"manithy.commit_boundary_event.v1","boundary_kind":"REFUND_COMMIT_T_MINUS_1","boundary_seq":1,"same_thread":true,"reentrancy_guard":"SINGLE_CAPTURE_ENFORCED","observed":{...},"availability":{...}}
+```
+
+## Capture Parameters
+
+| Parameter | Type | Purpose |
+|---|---|---|
+| **`boundary_kind`** | `str` | Which irreversible boundary this event refers to. Consumer-defined closed enum (e.g. `"REFUND_COMMIT_T_MINUS_1"`). |
+| **`boundary_seq`** | `int` | Supports rare cases of multiple irreversible calls in one execution path. Small integer (0–255). |
+| **`same_thread`** | `bool` | Runtime assertion that capture happened same-thread at t-1. |
+| **`observed`** | `dict[str, str\|int\|bool]` | Runtime facts already resolved in the execution context. Values must be primitives only — no floats, no `None`, no nested structures. |
+| **`availability`** | `dict[str, bool]` | Epistemic visibility at t-1. Each key declares whether a fact was knowable before the irreversible action. |
+| **`reentrancy_guard`** | `str` | Capture enforcement mode. Consumer-defined (e.g. `"SINGLE_CAPTURE_ENFORCED"`). |
+
+### The `observed` Block
+
+All fields in `observed` must already be resolved in the execution context at t-1.
+
+**Allowed:** `str`, `int`, `bool`.
+**Forbidden:** `float`, `None`, nested `dict`/`list`, any value fetched or inferred after execution.
+
+### The `availability` Block
+
+`availability` is not data. It is a **declaration of epistemic visibility** at t-1.
+
+Each key answers one question:
+> "At the exact moment before the irreversible action, was this fact already knowable inside the execution context — yes or no?"
+
+| `_known` value | Meaning | Effect |
+|---|---|---|
+| `True` | Fact was knowable at t-1 | May appear in `observed` |
+| `False` | Fact was NOT knowable at t-1 | Must NOT appear in `observed` |
+
+If the fact was not knowable, Manithy records **ignorance**, not a value.
+That ignorance is structural and permanent.
+
+### Forbidden Fields
+
+The following fields must **never** appear in a CommitBoundaryEvent:
+
+| Field | Why Forbidden |
+|---|---|
+| `producer_invocation_id` | High joinability risk. Single-capture is enforced via guard state, not IDs. |
+| `callsite_id` | High joinability risk. |
+| `producer_build_id` | Belongs in PackInit / EvidencePack provenance, not J01. |
+
+## Custom Buffer
+
+Route proofs to a file, queue, or any destination by subclassing `CaptureBuffer`:
+
+```python
+import json
+from manithy import ManithySDK
+from manithy.interfaces.buffer import CaptureBuffer
+
+class FileBuffer(CaptureBuffer):
+    def __init__(self, path: str):
+        self._file = open(path, "a", encoding="utf-8")
+
+    def emit(self, envelope: dict) -> None:
+        self._file.write(json.dumps(envelope, separators=(",", ":")) + "\n")
+        self._file.flush()
+
+sdk = ManithySDK(buffer=FileBuffer("audit.log"))
+```
+
+## Configuration
+
+### Kill-Switch
+
+Disable all capture at runtime without code changes:
+
+```bash
+export MANITHY_ENABLED=false   # Linux/macOS
+```
+
+```powershell
+$env:MANITHY_ENABLED = "false"  # Windows PowerShell
+```
+
+When disabled, `capture()` returns `{"status": "SKIPPED"}` immediately.
+
+### Debug Mode
+
+Log internal SDK errors to stderr (useful during development):
+
+```bash
+export MANITHY_DEBUG=true
+```
+
+## How It Works
+
+1. **Kill-switch check** — reads `MANITHY_ENABLED`. If `"false"`, returns `SKIPPED`.
+2. **Validation** — enforces type constraints on all fields; rejects forbidden fields, floats in `observed`, non-bool in `availability`, and unknown facts that leak into `observed`.
+3. **Event assembly** — builds a J01 `CommitBoundaryEvent` with schema `manithy.commit_boundary_event.v1`.
+4. **Hashing** — canonicalizes the event (sorted keys, no whitespace, floats like `100.0` → `100`) and computes SHA-256 → 64-char hex `commit_id`.
+5. **Emit** — writes the event to the configured buffer (default: stdout with `MANITHY_PROOF::` prefix).
+
+If any step fails, the error is swallowed and `{"status": "ERROR", "error": "Internal SDK Error"}` is returned. The host application is **never** affected.
+
+## Development
+
+```bash
+# Create a virtual environment
+python -m venv .venv
+
+# Activate it
+source .venv/bin/activate        # Linux/macOS
+.venv\Scripts\Activate.ps1       # Windows PowerShell
+
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+```
+
+## Project Structure
+
+```
+src/manithy/
+├── __init__.py      # Public API: exposes ManithySDK
+├── sdk.py           # Main entry point (capture pipeline + fail-closed)
+├── config.py        # Environment variable loader (kill-switch + debug)
+├── core/
+│   ├── canonical.py # Deterministic JSON canonicalization
+│   ├── hasher.py    # SHA-256 commit-ID generation
+│   └── envelope.py  # J01 CommitBoundaryEvent assembly + validation
+└── interfaces/
+    └── buffer.py    # Abstract CaptureBuffer + StdoutBuffer
+tests/
+├── vectors.json     # Golden test vectors (canonical + hash)
+├── test_core.py     # Core module tests (canonical, hasher, J01 event)
+└── test_sdk.py      # SDK integration tests (capture, kill-switch, fail-closed)
+```

manithy_sdk-0.1.0/README.md

@@ -0,0 +1,207 @@
+# Manithy SDK (Python)
+
+**Authority-Grade Audit Capture — Zero Dependencies**
+
+Manithy captures tamper-evident audit proofs at the application layer.
+Each proof is a **J01 CommitBoundaryEvent** — a structured record that
+marks the exact t-1 boundary before an irreversible action and freezes
+only facts already resolved in the execution context.
+
+No lookups. No inference. No enrichment.
+
+## Design Constraints
+
+| Constraint | Guarantee |
+|---|---|
+| **Zero Network I/O** | The SDK never opens sockets or makes HTTP calls. |
+| **Determinism** | Identical inputs always yield identical commit-IDs. |
+| **Fail-Closed** | Internal errors are silently swallowed — the host app never crashes. |
+| **Zero Dependencies** | Only the Python standard library is used at runtime. |
+| **Epistemic Honesty** | The `availability` block declares what was knowable at t-1. Unknown facts must never appear in `observed`. |
+
+## Installation
+
+```bash
+pip install manithy-sdk
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/VooYee/manithy-sdk.git
+cd manithy-sdk
+pip install .
+```
+
+## Quick Start
+
+```python
+from manithy import ManithySDK
+
+sdk = ManithySDK()
+
+result = sdk.capture(
+    boundary_kind="REFUND_COMMIT_T_MINUS_1",
+    boundary_seq=1,
+    same_thread=True,
+    observed={
+        "action_kind": "REFUND",
+        "amount_minor": 12900,
+        "currency": "EUR",
+        "refund_mode": "FULL",
+        "order_channel": "WEB",
+        "payment_method": "CARD",
+        "merchant_region": "EU",
+        "customer_present": False,
+        "operator_initiated": False,
+    },
+    availability={
+        "psp_refund_capability_known": True,
+        "original_payment_state_known": True,
+        "chargeback_state_known": False,
+    },
+    reentrancy_guard="SINGLE_CAPTURE_ENFORCED",
+)
+
+print(result)
+# {"status": "CAPTURED", "id": "a3f8c9..."}
+```
+
+Output (stdout):
+
+```
+MANITHY_PROOF::{"schema_id":"manithy.commit_boundary_event.v1","boundary_kind":"REFUND_COMMIT_T_MINUS_1","boundary_seq":1,"same_thread":true,"reentrancy_guard":"SINGLE_CAPTURE_ENFORCED","observed":{...},"availability":{...}}
+```
+
+## Capture Parameters
+
+| Parameter | Type | Purpose |
+|---|---|---|
+| **`boundary_kind`** | `str` | Which irreversible boundary this event refers to. Consumer-defined closed enum (e.g. `"REFUND_COMMIT_T_MINUS_1"`). |
+| **`boundary_seq`** | `int` | Supports rare cases of multiple irreversible calls in one execution path. Small integer (0–255). |
+| **`same_thread`** | `bool` | Runtime assertion that capture happened same-thread at t-1. |
+| **`observed`** | `dict[str, str\|int\|bool]` | Runtime facts already resolved in the execution context. Values must be primitives only — no floats, no `None`, no nested structures. |
+| **`availability`** | `dict[str, bool]` | Epistemic visibility at t-1. Each key declares whether a fact was knowable before the irreversible action. |
+| **`reentrancy_guard`** | `str` | Capture enforcement mode. Consumer-defined (e.g. `"SINGLE_CAPTURE_ENFORCED"`). |
+
+### The `observed` Block
+
+All fields in `observed` must already be resolved in the execution context at t-1.
+
+**Allowed:** `str`, `int`, `bool`.
+**Forbidden:** `float`, `None`, nested `dict`/`list`, any value fetched or inferred after execution.
+
+### The `availability` Block
+
+`availability` is not data. It is a **declaration of epistemic visibility** at t-1.
+
+Each key answers one question:
+> "At the exact moment before the irreversible action, was this fact already knowable inside the execution context — yes or no?"
+
+| `_known` value | Meaning | Effect |
+|---|---|---|
+| `True` | Fact was knowable at t-1 | May appear in `observed` |
+| `False` | Fact was NOT knowable at t-1 | Must NOT appear in `observed` |
+
+If the fact was not knowable, Manithy records **ignorance**, not a value.
+That ignorance is structural and permanent.
+
+### Forbidden Fields
+
+The following fields must **never** appear in a CommitBoundaryEvent:
+
+| Field | Why Forbidden |
+|---|---|
+| `producer_invocation_id` | High joinability risk. Single-capture is enforced via guard state, not IDs. |
+| `callsite_id` | High joinability risk. |
+| `producer_build_id` | Belongs in PackInit / EvidencePack provenance, not J01. |
+
+## Custom Buffer
+
+Route proofs to a file, queue, or any destination by subclassing `CaptureBuffer`:
+
+```python
+import json
+from manithy import ManithySDK
+from manithy.interfaces.buffer import CaptureBuffer
+
+class FileBuffer(CaptureBuffer):
+    def __init__(self, path: str):
+        self._file = open(path, "a", encoding="utf-8")
+
+    def emit(self, envelope: dict) -> None:
+        self._file.write(json.dumps(envelope, separators=(",", ":")) + "\n")
+        self._file.flush()
+
+sdk = ManithySDK(buffer=FileBuffer("audit.log"))
+```
+
+## Configuration
+
+### Kill-Switch
+
+Disable all capture at runtime without code changes:
+
+```bash
+export MANITHY_ENABLED=false   # Linux/macOS
+```
+
+```powershell
+$env:MANITHY_ENABLED = "false"  # Windows PowerShell
+```
+
+When disabled, `capture()` returns `{"status": "SKIPPED"}` immediately.
+
+### Debug Mode
+
+Log internal SDK errors to stderr (useful during development):
+
+```bash
+export MANITHY_DEBUG=true
+```
+
+## How It Works
+
+1. **Kill-switch check** — reads `MANITHY_ENABLED`. If `"false"`, returns `SKIPPED`.
+2. **Validation** — enforces type constraints on all fields; rejects forbidden fields, floats in `observed`, non-bool in `availability`, and unknown facts that leak into `observed`.
+3. **Event assembly** — builds a J01 `CommitBoundaryEvent` with schema `manithy.commit_boundary_event.v1`.
+4. **Hashing** — canonicalizes the event (sorted keys, no whitespace, floats like `100.0` → `100`) and computes SHA-256 → 64-char hex `commit_id`.
+5. **Emit** — writes the event to the configured buffer (default: stdout with `MANITHY_PROOF::` prefix).
+
+If any step fails, the error is swallowed and `{"status": "ERROR", "error": "Internal SDK Error"}` is returned. The host application is **never** affected.
+
+## Development
+
+```bash
+# Create a virtual environment
+python -m venv .venv
+
+# Activate it
+source .venv/bin/activate        # Linux/macOS
+.venv\Scripts\Activate.ps1       # Windows PowerShell
+
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+```
+
+## Project Structure
+
+```
+src/manithy/
+├── __init__.py      # Public API: exposes ManithySDK
+├── sdk.py           # Main entry point (capture pipeline + fail-closed)
+├── config.py        # Environment variable loader (kill-switch + debug)
+├── core/
+│   ├── canonical.py # Deterministic JSON canonicalization
+│   ├── hasher.py    # SHA-256 commit-ID generation
+│   └── envelope.py  # J01 CommitBoundaryEvent assembly + validation
+└── interfaces/
+    └── buffer.py    # Abstract CaptureBuffer + StdoutBuffer
+tests/
+├── vectors.json     # Golden test vectors (canonical + hash)
+├── test_core.py     # Core module tests (canonical, hasher, J01 event)
+└── test_sdk.py      # SDK integration tests (capture, kill-switch, fail-closed)
+```

manithy_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "manithy-sdk"
+version = "0.1.0"
+description = "Manithy SDK — Authority-Grade Audit Capture (Zero Dependencies)"
+readme = "README.md"
+license = { text = "Proprietary" }
+requires-python = ">=3.8"
+
+# ─────────────────────────────────────────────────────────────────────
+# CRITICAL CONSTRAINT: Zero External Dependencies
+# ─────────────────────────────────────────────────────────────────────
+# The Manithy SDK must NEVER add third-party runtime dependencies.
+# Every capability (hashing, JSON handling, I/O) must rely exclusively
+# on the Python standard library.  This guarantees:
+#   1. No supply-chain attack surface.
+#   2. No version-conflict issues in host applications.
+#   3. Deterministic, reproducible builds.
+# ─────────────────────────────────────────────────────────────────────
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

manithy_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

manithy_sdk-0.1.0/src/manithy/__init__.py

@@ -0,0 +1,17 @@
+"""
+Manithy SDK — Authority-Grade Audit Capture
+============================================
+
+Public API surface:
+    from manithy import ManithySDK
+
+Constraints:
+    - Zero Network I/O   → The SDK never opens sockets or makes HTTP calls.
+    - Determinism         → Identical inputs always yield identical outputs.
+    - Fail-Closed         → Any internal error is silently swallowed; the host
+                            application must never crash because of the SDK.
+"""
+
+from manithy.sdk import ManithySDK  # noqa: F401
+
+__all__ = ["ManithySDK"]

manithy_sdk-0.1.0/src/manithy/config.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import os
+
+
+def is_enabled() -> bool:
+    """Return whether the Manithy SDK is enabled.
+
+    Reads the ``MANITHY_ENABLED`` environment variable via
+    ``os.environ``.
+
+    * If the variable is **absent** → return ``True`` (enabled by
+      default).
+    * If the variable is set to ``"false"`` (case-insensitive) →
+      return ``False``.
+    * Any other value → return ``True``.
+
+    Returns
+    -------
+    bool
+        ``True`` if capture should proceed, ``False`` otherwise.
+    """
+    raw = os.environ.get("MANITHY_ENABLED", "true")
+    return raw.strip().lower() != "false"
+
+
+def is_debug() -> bool:
+    """Return whether debug mode is enabled.
+
+    Reads the ``MANITHY_DEBUG`` environment variable.
+
+    * If the variable is set to ``"true"`` (case-insensitive) →
+      return ``True``.
+    * Any other value (or absence) → return ``False``.
+
+    Returns
+    -------
+    bool
+        ``True`` if debug logging should be active, ``False`` otherwise.
+    """
+    raw = os.environ.get("MANITHY_DEBUG", "false")
+    return raw.strip().lower() == "true"

manithy_sdk-0.1.0/src/manithy/core/__init__.py

@@ -0,0 +1,10 @@
+"""
+manithy.core
+~~~~~~~~~~~~
+
+Core deterministic building blocks.  Every function in this package is
+pure (no side-effects, no I/O) and must be fully deterministic:
+    • canonical  - JSON canonicalization
+    • hasher     - SHA-256 commit-ID generation
+    • envelope   - J01 CommitBoundaryEvent assembly
+"""

manithy_sdk-0.1.0/src/manithy/core/canonical.py

@@ -0,0 +1,99 @@
+"""
+manithy.core.canonical
+~~~~~~~~~~~~~~~~~~~~~~
+
+Deterministic JSON Canonicalization.
+
+This module converts an arbitrary Python data structure (dicts, lists,
+primitives) into a **canonical byte string** that is identical across
+Python and Node.js for the same logical input.
+
+Owner: [Dev A]
+
+Cross-Language Determinism Rules
+--------------------------------
+1. **Sort object keys** — recursively, at every nesting level, using
+   standard lexicographic (Unicode code-point) order.
+
+2. **Strip insignificant whitespace** — the output must contain no
+  spaces or newlines between tokens (equivalent to
+  ``json.dumps(separators=(',', ':'))``).
+
+3. **Normalize numbers** —
+   * Floats that are mathematically integers (e.g. ``100.0``, ``3.0``)
+     **must** be emitted as integers (``100``, ``3``) so the byte output
+    matches what ``JSON.stringify`` produces in Node.js.
+   * Non-integer floats (e.g. ``3.14``) should be serialized with full
+    precision, avoiding trailing zeros.
+
+4. **Encoding** — the final output must be UTF-8 encoded ``bytes``.
+
+5. **No external libraries** — only ``json`` from the standard library.
+
+Example
+-------
+>>> to_canonical_bytes({"b": 1, "a": [3.0, {"d": 4, "c": 5}]})
+b'{"a":[3,{"c":5,"d":4}],"b":1}'
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def _normalize(data: Any, _seen: set) -> Any:
+    """Recursively normalize *data* for deterministic serialization.
+
+    - Sorts dict keys lexicographically.
+    - Converts whole-number floats to ints (the "float trap").
+    - Detects circular references via object-id tracking.
+    """
+    obj_id = id(data)
+    if isinstance(data, (dict, list)):
+        if obj_id in _seen:
+            raise ValueError("Circular reference detected")
+        _seen.add(obj_id)
+
+    if isinstance(data, dict):
+        result = {k: _normalize(v, _seen) for k, v in sorted(data.items())}
+        _seen.discard(obj_id)
+        return result
+
+    if isinstance(data, list):
+        result = [_normalize(item, _seen) for item in data]
+        _seen.discard(obj_id)
+        return result
+
+    if isinstance(data, float):
+        if data.is_integer():
+            return int(data)
+        return data
+
+    return data
+
+
+def to_canonical_bytes(data: Any) -> bytes:
+    """Convert *data* to deterministic, canonical UTF-8 JSON bytes.
+
+    Parameters
+    ----------
+    data : Any
+        Arbitrary JSON-serializable Python object (dict, list, str,
+        int, float, bool, None).
+
+    Returns
+    -------
+    bytes
+        UTF-8 encoded canonical JSON with sorted keys, no whitespace,
+        and floats-that-are-integers coerced to ints.
+
+    Raises
+    ------
+    TypeError
+        If *data* contains types that are not JSON-serializable.
+    ValueError
+        If *data* contains circular references.
+    """
+    normalized = _normalize(data, set())
+    return json.dumps(normalized, separators=(",", ":"), sort_keys=False).encode("utf-8")