subschema 0.0.2__tar.gz → 0.0.4__tar.gz

{subschema-0.0.2 → subschema-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: subschema
-Version: 0.0.2
+Version: 0.0.4
 Summary: A conservative JSON Schema subschema prover
 Project-URL: Homepage, https://github.com/ArakawaHenri/subschema
 Project-URL: Repository, https://github.com/ArakawaHenri/subschema
@@ -82,7 +82,26 @@ Available public entrypoints:
 - `canonicalize_schema(schema, *, dialect=None)`
 - `SchemaError`, `SubschemaError`, and `UnsupportedProofError` as stable catch points.
 
-The wheel includes `py.typed` for typed-package consumers.
+## Proof Behavior
+
+`subschema` proves sound results when it can. If a query is outside the current
+proof model, public boolean helpers raise `UnsupportedProofError` instead of
+guessing.
+
+Use `endeavor=True` or `--endeavor` for finite but potentially expensive proof
+products. In endeavor mode, `max_work` limits proof frontier expansion and
+`timeout_ms` limits solver calls. These controls are accepted only when endeavor
+is enabled.
+
+Current intentional boundaries:
+
+- external references are not fetched from the network;
+- recursive `$ref` and recursive dynamic-reference proofs are not modeled;
+- `format` is treated as an annotation unless a future assertion backend is
+  provided;
+- non-regular ECMAScript regex features such as backreferences and lookaround
+  are reported as unsupported;
+- `unsupported` means “not proven by this model,” not “the schema is invalid.”
 
 ## Dialects
 
@@ -98,8 +117,8 @@ Supported dialects:
 - Draft 2019-09
 - Draft 2020-12
 
-The prover is intentionally conservative. Unsupported, unbounded, recursive, or
-exhausted proof fragments are reported instead of being silently approximated.
+Resource exhaustion is reported separately from unsupported proof fragments when
+an endeavor proof exceeds its configured work or timeout limit.
 
 ## Acknowledgement
 

{subschema-0.0.2 → subschema-0.0.4}/README.md

@@ -65,7 +65,26 @@ Available public entrypoints:
 - `canonicalize_schema(schema, *, dialect=None)`
 - `SchemaError`, `SubschemaError`, and `UnsupportedProofError` as stable catch points.
 
-The wheel includes `py.typed` for typed-package consumers.
+## Proof Behavior
+
+`subschema` proves sound results when it can. If a query is outside the current
+proof model, public boolean helpers raise `UnsupportedProofError` instead of
+guessing.
+
+Use `endeavor=True` or `--endeavor` for finite but potentially expensive proof
+products. In endeavor mode, `max_work` limits proof frontier expansion and
+`timeout_ms` limits solver calls. These controls are accepted only when endeavor
+is enabled.
+
+Current intentional boundaries:
+
+- external references are not fetched from the network;
+- recursive `$ref` and recursive dynamic-reference proofs are not modeled;
+- `format` is treated as an annotation unless a future assertion backend is
+  provided;
+- non-regular ECMAScript regex features such as backreferences and lookaround
+  are reported as unsupported;
+- `unsupported` means “not proven by this model,” not “the schema is invalid.”
 
 ## Dialects
 
@@ -81,8 +100,8 @@ Supported dialects:
 - Draft 2019-09
 - Draft 2020-12
 
-The prover is intentionally conservative. Unsupported, unbounded, recursive, or
-exhausted proof fragments are reported instead of being silently approximated.
+Resource exhaustion is reported separately from unsupported proof fragments when
+an endeavor proof exceeds its configured work or timeout limit.
 
 ## Acknowledgement
 

{subschema-0.0.2 → subschema-0.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "subschema"
-version = "0.0.2"
+version = "0.0.4"
 description = "A conservative JSON Schema subschema prover"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -44,6 +44,7 @@ include = [
 [dependency-groups]
 dev = [
     "coverage[toml]",
+    "hypothesis>=6.155.1",
     "mypy>=2.1.0",
     "pytest",
     "ruff",

{subschema-0.0.2 → subschema-0.0.4}/src/subschema/api.py

@@ -15,7 +15,7 @@ from subschema.dialects import (
     validate_supported_keywords,
 )
 from subschema.kernel.contracts import ProofBudgets, ProofOptions
-from subschema.kernel.disjointness import schemas_are_disjoint
+from subschema.kernel.disjointness import schema_is_empty_exact, schemas_are_disjoint
 from subschema.kernel.engine import ProofEngine
 from subschema.kernel.json_data import ensure_json_value
 from subschema.kernel.normalization import normalize_boolean_schemas
@@ -202,12 +202,16 @@ def is_empty(
         timeout_ms=timeout_ms,
     )
     empty_schema = empty_schema_for_dialect(resolved_dialect)
-    return ProofEngine.for_schemas(
+    engine = ProofEngine.for_schemas(
         schema,
         empty_schema,
         dialect=resolved_dialect,
         options=options,
-    ).is_subschema_bool(schema, empty_schema)
+    )
+    exact_empty = schema_is_empty_exact(schema, engine.context)
+    if exact_empty.status != "unsupported":
+        return exact_empty.as_bool(resolved_dialect)
+    return engine.is_subschema_bool(schema, empty_schema)
 
 
 def is_disjoint(

{subschema-0.0.2 → subschema-0.0.4}/src/subschema/cli.py

@@ -2,6 +2,7 @@ import argparse
 from typing import TextIO, cast
 
 from subschema.api import is_subschema
+from subschema.exceptions import UnsupportedProofError
 from subschema.kernel import ProofBudgets, ProofOptions
 from subschema.kernel.json_data import strict_json_load
 from subschema.types import JSONSchema
@@ -25,6 +26,10 @@ def load_json_file(path: str, label: str) -> JSONSchema:
             raise SystemExit(f"{label} {err}") from err
 
 
+def format_unsupported_proof_error(error: UnsupportedProofError) -> str:
+    return error.format()
+
+
 def main() -> None:
     """CLI entry point for subschema"""
 
@@ -70,7 +75,13 @@ def main() -> None:
             ),
         )
 
-    print("LHS <: RHS", is_subschema(s1, s2, proof_options=proof_options))
+    try:
+        result = is_subschema(s1, s2, proof_options=proof_options)
+    except UnsupportedProofError as err:
+        message = format_unsupported_proof_error(err)
+        raise SystemExit(f"unsupported proof: {message}") from err
+
+    print("LHS <: RHS", result)
 
 
 if __name__ == "__main__":

{subschema-0.0.2 → subschema-0.0.4}/src/subschema/exceptions.py

@@ -1,10 +1,13 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from jsonschema.exceptions import SchemaError
 
+if TYPE_CHECKING:
+    from subschema.kernel.contracts import UnsupportedDiagnostic
+
 __all__ = [
     "ConflictingDialectError",
     "SchemaError",
@@ -26,13 +29,30 @@ class SubschemaError(Exception):
 class UnsupportedProofError(SubschemaError):
     """Raised when the prover cannot decide a supported public query."""
 
-    def __init__(self, reason: str, *, status: str | None = None):
+    def __init__(
+        self,
+        reason: str,
+        *,
+        status: str | None = None,
+        diagnostics: tuple[UnsupportedDiagnostic, ...] = (),
+    ):
         self.reason = reason
         self.status = status
+        self.diagnostics = diagnostics
 
     def __str__(self) -> str:
         return self.reason
 
+    def formatted_diagnostics(self) -> tuple[str, ...]:
+        return tuple(diagnostic.format() for diagnostic in self.diagnostics)
+
+    def format(self) -> str:
+        diagnostics = self.formatted_diagnostics()
+        if not diagnostics:
+            return self.reason
+        diagnostic_lines = "\n".join(f"- {diagnostic}" for diagnostic in diagnostics)
+        return f"{self.reason}\ndiagnostics:\n{diagnostic_lines}"
+
 
 class _UnsupportedCaseError(SubschemaError):
     pass

{subschema-0.0.2 → subschema-0.0.4}/src/subschema/kernel/applicators.py

@@ -153,9 +153,6 @@ __all__ = [
     "right_not_intersection_witness_plan",
     "right_not_resolved_rhs_schema",
     "right_not_subproof_choice",
-    "right_applicator_base_first_result_choice",
-    "right_applicator_branch_first_pre_base_choice",
-    "right_applicator_branch_first_result_choice",
     "right_negative_all_of_branch_product_plan",
     "right_negative_all_of_branch_proof_choice",
     "right_negative_any_of_branch_product_plan",
@@ -801,44 +798,6 @@ def applicator_base_pre_branch_choice(
     return "continue"
 
 
-def right_applicator_base_first_result_choice(
-    base_status: ProofStatus,
-    branch_status: ProofStatus,
-) -> ApplicatorProofChoice:
-    if base_status == "proved_false":
-        return "base_false"
-    if branch_status == "proved_false":
-        return "branch"
-    if base_status == "resource_exhausted":
-        return "base"
-    if branch_status == "proved_true" and base_status == "proved_true":
-        return "proved_true"
-    if branch_status == "proved_true":
-        return "base"
-    return "branch"
-
-
-def right_applicator_branch_first_pre_base_choice(
-    branch_status: ProofStatus,
-) -> ApplicatorProofChoice:
-    if branch_status in {"proved_false", "resource_exhausted"}:
-        return "branch"
-    return "continue"
-
-
-def right_applicator_branch_first_result_choice(
-    base_status: ProofStatus,
-    branch_status: ProofStatus,
-) -> ApplicatorProofChoice:
-    if base_status == "proved_false":
-        return "base_false"
-    if base_status in {"unsupported", "resource_exhausted"}:
-        return "base"
-    if branch_status == "proved_true":
-        return "proved_true"
-    return "branch"
-
-
 def right_negative_any_of_branch_proof_choice(
     status: ProofStatus,
 ) -> ApplicatorBranchProofChoice:

{subschema-0.0.2 → subschema-0.0.4}/src/subschema/kernel/context.py

@@ -5,7 +5,7 @@ Proof context, policy, and budget state for the kernel.
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any
+from typing import Any
 
 import subschema.kernel.driver as proof_driver
 from subschema.dialects import Dialect
@@ -17,9 +17,6 @@ from subschema.kernel.contracts import (
 )
 from subschema.kernel.values import stable_key
 
-if TYPE_CHECKING:
-    from subschema.kernel.evaluation import EvaluationExpression
-
 _EXPENSIVE_PROOF_WORK_LABELS: dict[ExpensiveProofKind, str] = {
     "array_product": "array product",
     "branch_product": "branch expansion",
@@ -36,9 +33,7 @@ class ProofContext:
     dialect: Dialect
     options: ProofOptions = field(default_factory=ProofOptions)
     subproof_cache: dict[tuple[Any, ...], ProofResult] = field(default_factory=dict)
-    evaluation_expression_cache: dict[tuple[Any, ...], EvaluationExpression] = field(
-        default_factory=dict
-    )
+    cache: dict[tuple[object, ...], object] = field(default_factory=dict)
     work_meter: ProofWorkMeter = field(init=False)
 
     def __post_init__(self) -> None:
@@ -72,6 +67,15 @@ class ProofContext:
             stable_key(rhs),
         )
 
+    def cache_get(self, namespace: str, key: tuple[Any, ...]) -> object | None:
+        return self.cache.get(self._cache_key(namespace, key))
+
+    def cache_set(self, namespace: str, key: tuple[Any, ...], value: object) -> None:
+        self.cache[self._cache_key(namespace, key)] = value
+
+    def _cache_key(self, namespace: str, key: tuple[Any, ...]) -> tuple[object, ...]:
+        return (namespace, *(_cache_key_part(part) for part in key))
+
     def consume_branch_expansion(self, reason: str) -> ProofResult | None:
         return self.spend_work(1, "branch expansion", reason)
 
@@ -132,3 +136,11 @@ class ProofContext:
         from subschema.kernel.projection import ProjectionEngine
 
         return ProjectionEngine(self).finite_join_projection(lhs, rhs)
+
+
+def _cache_key_part(part: Any) -> object:
+    try:
+        hash(part)
+    except TypeError:
+        return stable_key(part)
+    return part

{subschema-0.0.2 → subschema-0.0.4}/src/subschema/kernel/contracts.py

@@ -106,6 +106,20 @@ class ProofResult:
     error: Exception | None = None
     diagnostics: tuple[UnsupportedDiagnostic, ...] = ()
 
+    def __repr__(self) -> str:
+        parts = [f"status={self.status!r}"]
+        if self.reason is not None:
+            parts.append(f"reason={self.reason!r}")
+        if self.diagnostics:
+            parts.append(f"diagnostics={len(self.diagnostics)}")
+        if self.certificate is not None:
+            parts.append(f"certificate={self.certificate.kind!r}")
+        if self.witness is not None:
+            parts.append(f"witness_type={type(self.witness).__name__}")
+        if self.error is not None:
+            parts.append(f"error={type(self.error).__name__}")
+        return f"{type(self).__name__}({', '.join(parts)})"
+
     @classmethod
     def true(cls) -> ProofResult:
         return cls("proved_true")
@@ -155,6 +169,7 @@ class ProofResult:
         raise UnsupportedProofError(
             self.reason or "schema proof could not be proven",
             status=self.status,
+            diagnostics=self.diagnostics,
         )