worldcut 0.1.1__tar.gz

worldcut-0.1.1/.gitignore

@@ -0,0 +1,12 @@
+/.venv/
+/.wheel-venv/
+/.sdist-venv/
+/.sdist-test/
+/dist/
+/.pytest_cache/
+/.mypy_cache/
+/.ruff_cache/
+/.hypothesis/
+*.egg-info/
+__pycache__/
+*.py[cod]

worldcut-0.1.1/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.5
+Name: worldcut
+Version: 0.1.1
+Summary: Independent Python verifier for the WorldCut decision-coherence protocol
+Project-URL: Homepage, https://github.com/Jason-Doyle/WorldCut
+Project-URL: Issues, https://github.com/Jason-Doyle/WorldCut/issues
+Project-URL: Repository, https://github.com/Jason-Doyle/WorldCut
+Author: Jason Doyle
+License-Expression: Apache-2.0
+Keywords: consistency,distributed-systems,provenance,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: rfc8785==0.1.4
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: hypothesis>=6.130; extra == 'dev'
+Requires-Dist: mypy>=1.15; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Requires-Dist: twine>=6.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# WorldCut Python
+
+Independent Python implementation of WorldCut protocol **0.1**, engine
+**0.1.2**, and canonicalization **worldcut-json-v1**. Python 3.11 or newer is
+required.
+
+## Install
+
+Install from PyPI after the `0.1.1` registry release is live:
+
+```sh
+python -m pip install worldcut==0.1.1
+```
+
+Until then, or when a source install is preferred, use the protected tag:
+
+```sh
+python -m pip install "worldcut @ git+https://github.com/Jason-Doyle/WorldCut.git@ports/python/v0.1.1#subdirectory=ports/python"
+```
+
+## Library
+
+```python
+from pathlib import Path
+
+from worldcut import parse_input, verify
+
+parsed = parse_input(Path("verification.json").read_bytes())
+result = verify(parsed)
+print(result["verdict"])
+print(result["verificationRecordDigest"])
+```
+
+`ParsedInput` is an immutable validated snapshot. Every verification returns a
+fresh result, so mutating one result cannot affect later verification.
+
+## CLI
+
+```sh
+worldcut-py verification.json
+worldcut-py --require-satisfied verification.json
+```
+
+The second form exits with status 2 unless the verdict is
+`CONTRACT_SATISFIED`.
+
+## Validate
+
+```sh
+python -m pip install -e ".[dev]"
+ruff format --check .
+ruff check .
+mypy src
+pytest
+python -m build
+twine check dist/*
+```
+
+The source distribution includes the complete mirrored conformance corpus and
+can run its tests without files from the parent repository. This port includes
+the verifier and CLI only; integrations are intentionally not included yet.

worldcut-0.1.1/README.md

@@ -0,0 +1,61 @@
+# WorldCut Python
+
+Independent Python implementation of WorldCut protocol **0.1**, engine
+**0.1.2**, and canonicalization **worldcut-json-v1**. Python 3.11 or newer is
+required.
+
+## Install
+
+Install from PyPI after the `0.1.1` registry release is live:
+
+```sh
+python -m pip install worldcut==0.1.1
+```
+
+Until then, or when a source install is preferred, use the protected tag:
+
+```sh
+python -m pip install "worldcut @ git+https://github.com/Jason-Doyle/WorldCut.git@ports/python/v0.1.1#subdirectory=ports/python"
+```
+
+## Library
+
+```python
+from pathlib import Path
+
+from worldcut import parse_input, verify
+
+parsed = parse_input(Path("verification.json").read_bytes())
+result = verify(parsed)
+print(result["verdict"])
+print(result["verificationRecordDigest"])
+```
+
+`ParsedInput` is an immutable validated snapshot. Every verification returns a
+fresh result, so mutating one result cannot affect later verification.
+
+## CLI
+
+```sh
+worldcut-py verification.json
+worldcut-py --require-satisfied verification.json
+```
+
+The second form exits with status 2 unless the verdict is
+`CONTRACT_SATISFIED`.
+
+## Validate
+
+```sh
+python -m pip install -e ".[dev]"
+ruff format --check .
+ruff check .
+mypy src
+pytest
+python -m build
+twine check dist/*
+```
+
+The source distribution includes the complete mirrored conformance corpus and
+can run its tests without files from the parent repository. This port includes
+the verifier and CLI only; integrations are intentionally not included yet.

worldcut-0.1.1/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling==1.32.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "worldcut"
+version = "0.1.1"
+description = "Independent Python verifier for the WorldCut decision-coherence protocol"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "Jason Doyle" }]
+keywords = ["consistency", "distributed-systems", "provenance", "verification"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = ["rfc8785==0.1.4"]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2",
+  "hypothesis>=6.130",
+  "mypy>=1.15",
+  "pytest>=8.3",
+  "ruff>=0.11",
+  "twine>=6.1",
+]
+
+[project.scripts]
+worldcut-py = "worldcut.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Jason-Doyle/WorldCut"
+Issues = "https://github.com/Jason-Doyle/WorldCut/issues"
+Repository = "https://github.com/Jason-Doyle/WorldCut"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/worldcut"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src/worldcut",
+  "/tests",
+  "/README.md",
+  "/pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-config --strict-markers"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "RUF", "SIM", "UP"]

worldcut-0.1.1/src/worldcut/__init__.py

@@ -0,0 +1,30 @@
+"""Independent Python implementation of the WorldCut 0.1 verifier."""
+
+from .canonicalization import canonical_json, sha256_digest
+from .errors import WorldCutError, WorldCutErrorCode, WorldCutInputError
+from .models import ParsedInput, VerificationResult
+from .validation import PROTOCOL_VERSION, parse_input
+from .verifier import (
+    CANONICALIZATION,
+    ENGINE_VERSION,
+    verify,
+    verify_json,
+)
+
+__all__ = [
+    "CANONICALIZATION",
+    "ENGINE_VERSION",
+    "PROTOCOL_VERSION",
+    "ParsedInput",
+    "VerificationResult",
+    "WorldCutError",
+    "WorldCutErrorCode",
+    "WorldCutInputError",
+    "canonical_json",
+    "parse_input",
+    "sha256_digest",
+    "verify",
+    "verify_json",
+]
+
+__version__ = "0.1.1"

worldcut-0.1.1/src/worldcut/canonicalization.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import hashlib
+import math
+
+import rfc8785
+
+from .models import JsonValue
+
+_MAX_SAFE_INTEGER = 9_007_199_254_740_991
+
+
+def _assert_valid_unicode(value: str, field: str) -> None:
+    for character in value:
+        code_point = ord(character)
+        if 0xD800 <= code_point <= 0xDFFF:
+            raise TypeError(f"{field} contains an unpaired surrogate")
+
+
+def _snapshot_json(value: object, field: str, ancestors: set[int]) -> JsonValue:
+    if value is None or isinstance(value, (str, bool)):
+        if isinstance(value, str):
+            _assert_valid_unicode(value, field)
+        return value
+    if isinstance(value, int) and not isinstance(value, bool):
+        if abs(value) > _MAX_SAFE_INTEGER:
+            raise TypeError(f"{field} contains an integer outside the safe domain")
+        return value
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise TypeError(f"{field} contains a non-finite number")
+        return value
+    if type(value) is list:
+        identity = id(value)
+        if identity in ancestors:
+            raise TypeError(f"{field} must not contain cycles")
+        ancestors.add(identity)
+        array_result = [
+            _snapshot_json(item, f"{field}[{index}]", ancestors)
+            for index, item in enumerate(value)
+        ]
+        ancestors.remove(identity)
+        return array_result
+    if type(value) is dict:
+        identity = id(value)
+        if identity in ancestors:
+            raise TypeError(f"{field} must not contain cycles")
+        ancestors.add(identity)
+        object_result: dict[str, JsonValue] = {}
+        for raw_key, item in value.items():
+            if not isinstance(raw_key, str):
+                raise TypeError(f"{field} must use string object keys")
+            _assert_valid_unicode(raw_key, f"{field} key")
+            object_result[raw_key] = _snapshot_json(
+                item, f"{field}.{raw_key}", ancestors
+            )
+        ancestors.remove(identity)
+        return object_result
+    raise TypeError(f"{field} contains unsupported {type(value).__name__} data")
+
+
+def canonical_json(value: JsonValue) -> str:
+    """Return the worldcut-json-v1 canonical representation of JSON data."""
+
+    snapshot = _snapshot_json(value, "value", set())
+    try:
+        return rfc8785.dumps(snapshot).decode("utf-8")
+    except (rfc8785.CanonicalizationError, UnicodeError) as error:
+        raise TypeError(f"cannot canonicalize JSON data: {error}") from error
+
+
+def sha256_digest(value: JsonValue) -> str:
+    """Return the lowercase SHA-256 digest of canonical JSON data."""
+
+    return hashlib.sha256(canonical_json(value).encode("utf-8")).hexdigest()
+
+
+def utf16_sort_key(value: str) -> bytes:
+    """Produce the protocol's raw UTF-16 code-unit ordering key."""
+
+    _assert_valid_unicode(value, "text")
+    return value.encode("utf-16-be")

worldcut-0.1.1/src/worldcut/cli.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from .errors import WorldCutError
+from .verifier import verify_json
+
+
+def _usage() -> str:
+    return "\n".join(
+        [
+            "Usage: worldcut-py [--require-satisfied] <verification.json>",
+            "",
+            "Options:",
+            "  --require-satisfied  Exit with code 2 unless the contract is satisfied",
+            "  --help               Show this help",
+        ]
+    )
+
+
+def _write_error(code: str, message: str) -> None:
+    print(
+        json.dumps({"error": {"code": code, "message": message}}),
+        file=sys.stderr,
+    )
+
+
+def run(arguments: list[str] | None = None) -> int:
+    """Run the WorldCut CLI and return its process exit status."""
+
+    arguments = list(sys.argv[1:] if arguments is None else arguments)
+    if "--help" in arguments:
+        print(_usage())
+        return 0
+    require_satisfied = False
+    positional: list[str] = []
+    for argument in arguments:
+        if argument == "--require-satisfied":
+            require_satisfied = True
+        elif argument.startswith("-"):
+            _write_error("WORLDCUT_INVALID_ARGUMENT", f"Unknown option: {argument}")
+            return 1
+        else:
+            positional.append(argument)
+    if len(positional) != 1:
+        _write_error(
+            "WORLDCUT_INVALID_ARGUMENT",
+            "Exactly one verification JSON file is required",
+        )
+        return 1
+    path = Path(positional[0]).resolve()
+    try:
+        source = path.read_bytes()
+    except OSError:
+        _write_error("WORLDCUT_FILE_READ_FAILED", f"Unable to read {path}")
+        return 1
+    try:
+        result = verify_json(source)
+    except WorldCutError as error:
+        _write_error(error.code, str(error))
+        return 1
+    print(json.dumps(result, indent=2))
+    if require_satisfied and result["verdict"] != "CONTRACT_SATISFIED":
+        return 2
+    return 0
+
+
+def main() -> None:
+    """Console-script entry point."""
+
+    raise SystemExit(run())
+
+
+if __name__ == "__main__":
+    main()

worldcut-0.1.1/src/worldcut/errors.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Literal, TypeAlias
+
+WorldCutErrorCode: TypeAlias = Literal[
+    "WORLDCUT_INVALID_INPUT",
+    "WORLDCUT_INVALID_ARGUMENT",
+    "WORLDCUT_FILE_READ_FAILED",
+    "WORLDCUT_RUNTIME_ERROR",
+]
+
+
+class WorldCutError(Exception):
+    """Base exception carrying a stable WorldCut error code."""
+
+    code: WorldCutErrorCode
+
+    def __init__(self, code: WorldCutErrorCode, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class WorldCutInputError(WorldCutError):
+    """Raised when transport data violates the WorldCut protocol."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__("WORLDCUT_INVALID_INPUT", message)