worldcut 0.1.1__py3-none-any.whl

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/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/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/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)

worldcut/models.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Literal, NotRequired, TypeAlias, TypedDict
+
+JsonPrimitive: TypeAlias = str | int | float | bool | None
+JsonValue: TypeAlias = JsonPrimitive | list["JsonValue"] | dict[str, "JsonValue"]
+FrozenJson: TypeAlias = (
+    JsonPrimitive | tuple["FrozenJson", ...] | Mapping[str, "FrozenJson"]
+)
+
+Provenance: TypeAlias = Literal[
+    "provider_asserted",
+    "client_observed",
+    "derived",
+    "operator_supplied",
+]
+RequirementStatus: TypeAlias = Literal["SATISFIED", "VIOLATED", "UNKNOWN"]
+ContractVerdict: TypeAlias = Literal[
+    "CONTRACT_SATISFIED",
+    "CONTRACT_VIOLATED",
+    "INSUFFICIENT_EVIDENCE",
+]
+RequirementType: TypeAlias = Literal["dependency", "common_valid_time", "value_equals"]
+AcquisitionActionType: TypeAlias = Literal[
+    "REFRESH_OBSERVATION",
+    "FETCH_REQUIRED_METADATA",
+    "ACQUIRE_COMPATIBLE_EVIDENCE",
+]
+
+
+class AcquisitionAction(TypedDict):
+    id: str
+    type: AcquisitionActionType
+    role: str
+    cost: int
+    description: str
+    expected: JsonValue
+
+
+class AcquisitionOption(TypedDict):
+    id: str
+    description: str
+    actions: list[AcquisitionAction]
+
+
+class RequirementResult(TypedDict):
+    requirementId: str
+    requirementType: RequirementType
+    required: bool
+    status: RequirementStatus
+    summary: str
+    details: JsonValue
+    acquisitionOptions: list[AcquisitionOption]
+
+
+class AcquisitionPlan(TypedDict):
+    status: Literal["NOT_NEEDED", "AVAILABLE", "INCOMPLETE"]
+    reason: str | None
+    actions: list[AcquisitionAction]
+    selectedOptionIds: list[str]
+    totalCost: int
+    coveredRequirementIds: list[str]
+    unresolvedRequirementIds: list[str]
+
+
+class VerificationCoverage(TypedDict):
+    required: int
+    satisfied: int
+    violated: int
+    unknown: int
+    advisory: int
+
+
+class VerificationResult(TypedDict):
+    protocolVersion: Literal["0.1"]
+    engineVersion: str
+    canonicalization: Literal["worldcut-json-v1"]
+    contractId: str
+    contractVersion: str
+    verdict: ContractVerdict
+    coverage: VerificationCoverage
+    requirementResults: list[RequirementResult]
+    acquisitionPlan: AcquisitionPlan
+    verificationRecordDigest: str
+
+
+class ResourceInput(TypedDict):
+    provider: str
+    account: str
+    kind: str
+    key: str
+
+
+class ValidityInput(TypedDict):
+    from_: str
+    until: str | None
+
+
+class DependencyInput(TypedDict):
+    name: str
+    resource: ResourceInput
+    relation: Literal["exact"]
+    provenance: Provenance
+    version: NotRequired[str]
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceIdentity:
+    provider: str
+    account: str
+    kind: str
+    key: str
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class NormalizedTimestamp:
+    order: int
+    text: str = field(compare=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ValidityInterval:
+    from_text: str
+    until_text: str | None
+    start: NormalizedTimestamp
+    end: NormalizedTimestamp | None
+
+
+@dataclass(frozen=True, slots=True)
+class DependencyWitness:
+    name: str
+    resource: ResourceIdentity
+    relation: Literal["exact"]
+    version: str | None
+    provenance: Provenance
+
+
+@dataclass(frozen=True, slots=True)
+class ObservationWitness:
+    provenance: Provenance
+    version: str | None
+    validity: ValidityInterval | None
+    dependencies: tuple[DependencyWitness, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class Observation:
+    id: str
+    role: str
+    resource: ResourceIdentity
+    value: FrozenJson
+    observed_at_text: str
+    observed_at: NormalizedTimestamp
+    acquisition_cost: int
+    witness: ObservationWitness
+    raw: Mapping[str, FrozenJson]
+
+
+@dataclass(frozen=True, slots=True)
+class RequirementBase:
+    id: str
+    description: str
+    required: bool
+    raw: Mapping[str, FrozenJson]
+
+
+@dataclass(frozen=True, slots=True)
+class DependencyRequirement(RequirementBase):
+    type: Literal["dependency"]
+    dependent_role: str
+    target_role: str
+    dependency_name: str
+
+
+@dataclass(frozen=True, slots=True)
+class CommonValidTimeRequirement(RequirementBase):
+    type: Literal["common_valid_time"]
+    roles: tuple[str, ...]
+    within: ValidityInterval
+
+
+@dataclass(frozen=True, slots=True)
+class ValueEqualsRequirement(RequirementBase):
+    type: Literal["value_equals"]
+    role: str
+    path: tuple[str, ...]
+    expected: FrozenJson
+
+
+Requirement: TypeAlias = (
+    DependencyRequirement | CommonValidTimeRequirement | ValueEqualsRequirement
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Contract:
+    id: str
+    version: str
+    decision_time_text: str
+    decision_time: NormalizedTimestamp
+    requirements: tuple[Requirement, ...]
+    raw: Mapping[str, FrozenJson]
+
+
+@dataclass(frozen=True, slots=True)
+class _VerificationInput:
+    protocol_version: Literal["0.1"]
+    contract: Contract
+    observations: tuple[Observation, ...]
+
+
+_PARSED_INPUT_TOKEN = object()
+
+
+class ParsedInput:
+    """Opaque immutable handle returned by :func:`worldcut.parse_input`."""
+
+    __slots__ = ("__value",)
+    __value: _VerificationInput
+
+    def __init__(self, value: _VerificationInput, token: object) -> None:
+        if token is not _PARSED_INPUT_TOKEN:
+            raise TypeError("ParsedInput must be produced by parse_input")
+        object.__setattr__(self, "_ParsedInput__value", value)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        raise AttributeError("ParsedInput is immutable")
+
+    def _unwrap(self) -> _VerificationInput:
+        return self.__value
+
+
+def _new_parsed_input(value: _VerificationInput) -> ParsedInput:
+    return ParsedInput(value, _PARSED_INPUT_TOKEN)
+
+
+def _unwrap_parsed_input(value: ParsedInput) -> _VerificationInput:
+    if not isinstance(value, ParsedInput):
+        raise TypeError("verification input must be produced by parse_input")
+    return value._unwrap()
+
+
+def freeze_json(value: JsonValue) -> FrozenJson:
+    if isinstance(value, dict):
+        return MappingProxyType({key: freeze_json(item) for key, item in value.items()})
+    if isinstance(value, list):
+        return tuple(freeze_json(item) for item in value)
+    return value
+
+
+def thaw_json(value: FrozenJson) -> JsonValue:
+    if isinstance(value, Mapping):
+        return {key: thaw_json(item) for key, item in value.items()}
+    if isinstance(value, tuple):
+        return [thaw_json(item) for item in value]
+    return value

worldcut/planning.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .canonicalization import utf16_sort_key
+from .errors import WorldCutInputError
+from .models import AcquisitionAction, AcquisitionPlan, RequirementResult
+
+MAX_UNRESOLVED_REQUIREMENTS = 64
+MAX_OPTION_COMBINATIONS = 65_536
+MAX_SEARCH_STATES = (MAX_UNRESOLVED_REQUIREMENTS + 1) * MAX_OPTION_COMBINATIONS
+MAX_ACQUISITION_COST = 1_000_000_000
+MAX_PLAN_TOTAL_COST = 64_000_000_000
+
+
+@dataclass(slots=True)
+class _SearchState:
+    index: int
+    option_ids: list[str]
+    actions: dict[str, AcquisitionAction]
+    cost: int
+
+
+@dataclass(slots=True)
+class _Candidate:
+    option_ids: list[str]
+    actions: list[AcquisitionAction]
+    cost: int
+
+
+def _candidate_key(candidate: _Candidate) -> tuple[int, int, bytes]:
+    return (
+        candidate.cost,
+        len(candidate.actions),
+        utf16_sort_key("\0".join(candidate.option_ids)),
+    )
+
+
+def _incomplete(reason: str, unresolved: list[RequirementResult]) -> AcquisitionPlan:
+    return {
+        "status": "INCOMPLETE",
+        "reason": reason,
+        "actions": [],
+        "selectedOptionIds": [],
+        "totalCost": 0,
+        "coveredRequirementIds": [],
+        "unresolvedRequirementIds": [result["requirementId"] for result in unresolved],
+    }
+
+
+def _add_option(
+    state: _SearchState, option_id: str, option_actions: list[AcquisitionAction]
+) -> _SearchState:
+    actions = dict(state.actions)
+    cost = state.cost
+    for action in option_actions:
+        action_cost = action["cost"]
+        if action_cost < 0 or action_cost > MAX_ACQUISITION_COST:
+            raise WorldCutInputError(
+                f"Acquisition action {action['id']} cost must be between 0 and "
+                f"{MAX_ACQUISITION_COST}"
+            )
+        existing = actions.get(action["id"])
+        if existing is not None:
+            if existing["cost"] != action_cost:
+                raise RuntimeError(
+                    f"Acquisition action {action['id']} has conflicting declared costs"
+                )
+            continue
+        if cost > MAX_PLAN_TOTAL_COST - action_cost:
+            raise WorldCutInputError(
+                f"Acquisition plan cost exceeds {MAX_PLAN_TOTAL_COST}"
+            )
+        actions[action["id"]] = action
+        cost += action_cost
+    return _SearchState(
+        index=state.index + 1,
+        option_ids=[*state.option_ids, option_id],
+        actions=actions,
+        cost=cost,
+    )
+
+
+def select_acquisition_plan(
+    requirement_results: list[RequirementResult],
+) -> AcquisitionPlan:
+    """Select the exact minimum-cost acquisition plan within protocol limits."""
+
+    unresolved = sorted(
+        (
+            result
+            for result in requirement_results
+            if result["required"] and result["status"] != "SATISFIED"
+        ),
+        key=lambda result: utf16_sort_key(result["requirementId"]),
+    )
+    if not unresolved:
+        return {
+            "status": "NOT_NEEDED",
+            "reason": None,
+            "actions": [],
+            "selectedOptionIds": [],
+            "totalCost": 0,
+            "coveredRequirementIds": [],
+            "unresolvedRequirementIds": [],
+        }
+    if len(unresolved) > MAX_UNRESOLVED_REQUIREMENTS:
+        return _incomplete(
+            "Acquisition planning supports at most 64 unresolved requirements.",
+            unresolved,
+        )
+
+    coverable: list[RequirementResult] = []
+    impossible: list[str] = []
+    combinations = 1
+    for result in unresolved:
+        options = result["acquisitionOptions"]
+        if not options:
+            impossible.append(result["requirementId"])
+            continue
+        if combinations > MAX_OPTION_COMBINATIONS // len(options):
+            return _incomplete(
+                "Acquisition search exceeds the 65536 combination limit.",
+                unresolved,
+            )
+        combinations *= len(options)
+        coverable.append(result)
+
+    stack = [_SearchState(index=0, option_ids=[], actions={}, cost=0)]
+    best: _Candidate | None = None
+    visited = 0
+    while stack:
+        visited += 1
+        if visited > MAX_SEARCH_STATES:
+            return _incomplete(
+                "Acquisition search exceeds the 4259840 state limit.",
+                unresolved,
+            )
+        state = stack.pop()
+        if best is not None and state.cost > best.cost:
+            continue
+        if state.index >= len(coverable):
+            candidate = _Candidate(
+                option_ids=sorted(state.option_ids, key=utf16_sort_key),
+                actions=sorted(
+                    state.actions.values(),
+                    key=lambda action: utf16_sort_key(action["id"]),
+                ),
+                cost=state.cost,
+            )
+            if best is None or _candidate_key(candidate) < _candidate_key(best):
+                best = candidate
+            continue
+        options = sorted(
+            coverable[state.index]["acquisitionOptions"],
+            key=lambda option: utf16_sort_key(option["id"]),
+        )
+        for option in reversed(options):
+            next_state = _add_option(state, option["id"], option["actions"])
+            if best is None or next_state.cost <= best.cost:
+                stack.append(next_state)
+
+    if best is None:
+        return _incomplete(
+            "Acquisition search completed without a valid option set.",
+            unresolved,
+        )
+    impossible.sort(key=utf16_sort_key)
+    return {
+        "status": "AVAILABLE" if not impossible else "INCOMPLETE",
+        "reason": (
+            None
+            if not impossible
+            else (f"No acquisition option is available for: {', '.join(impossible)}.")
+        ),
+        "actions": best.actions,
+        "selectedOptionIds": best.option_ids,
+        "totalCost": best.cost,
+        "coveredRequirementIds": [result["requirementId"] for result in coverable],
+        "unresolvedRequirementIds": impossible,
+    }