feat(graphs): add canonical graph6 decoding and verification

Author: morluto

src/jacobian/domains/graph_optimization/graph6.py

@@ -0,0 +1,86 @@
+"""Typed graph6 operation and checker declaration."""
+
+from __future__ import annotations
+
+from pydantic import Field, StrictStr
+
+from jacobian.capability_service import CapabilityDiagnostic
+from jacobian.checker_operations import ExactReplayCheckerDeclaration
+from jacobian.contracts.base import ContractModel
+from jacobian.domains._examples import example
+from jacobian.math.graphs.graph6 import Graph6DecodeValue, decode_graph6
+from jacobian.operation_bindings import inline_operation
+from jacobian.operations import OperationRefusalError, OperationSpec
+
+
+class Graph6DecodeRequest(ContractModel):
+    graph6: StrictStr = Field(min_length=1, max_length=352)
+
+
+def _decode(request: Graph6DecodeRequest) -> Graph6DecodeValue:
+    try:
+        return decode_graph6(request.graph6)
+    except ValueError as exc:
+        raise OperationRefusalError(
+            CapabilityDiagnostic(
+                code="GRAPH6_DECODE_REFUSED",
+                stage="graph6_decoding",
+                message=str(exc),
+                hint=(
+                    "Supply standard small-order graph6 (orders 0-62), optionally "
+                    "prefixed by >>graph6<<; sparse6, digraph6, extended headers, "
+                    "invalid lengths, characters, and padding are rejected."
+                ),
+            )
+        ) from exc
+
+
+GRAPH6_CAPABILITIES = (
+    inline_operation(
+        OperationSpec(
+            operation_id="graph.encoding.graph6.decode.compute",
+            version="1",
+            title="Decode canonical small-order graph6",
+            description=(
+                "Decode a headerless or standard-header graph6 string of order at "
+                "most 62 using the column-major upper-triangle bit convention, "
+                "returning sorted edges, degrees, and a canonical graph digest."
+            ),
+            request_type=Graph6DecodeRequest,
+            result_type=Graph6DecodeValue,
+            execute=_decode,
+            tags=("graph", "encoding", "graph6", "deterministic", "exact"),
+            invocation_examples=(
+                example(
+                    "triangle_graph6",
+                    "Decode the graph6 representation of the triangle graph.",
+                    {"graph6": "Bw"},
+                ),
+            ),
+        )
+    ),
+)
+
+GRAPH6_CHECKER_DECLARATIONS = (
+    ExactReplayCheckerDeclaration(
+        "graph.encoding.graph6.decode.compute",
+        Graph6DecodeRequest,
+        "check_graph6_decode",
+        "graph.graph6-decode.standard-library-v1",
+        entrypoint_module="jacobian_checkers.graph6",
+        replay_method="standard-library graph6 bitstream replay",
+        reason=(
+            "operator-authorized standard-library checker independently decodes "
+            "the graph6 bitstream without importing the producer"
+        ),
+        verification_capability_id="graph.encoding.graph6.decode.verify",
+        verification_title="Verify a canonical graph6 decode",
+        verification_description=(
+            "Independently replay the small-order graph6 header, upper-triangle "
+            "bits, padding, sorted edges, degrees, and canonical graph digest."
+        ),
+        verification_tags=("verification", "exact", "graph", "encoding", "graph6"),
+    ),
+)
+
+__all__ = ["GRAPH6_CAPABILITIES", "GRAPH6_CHECKER_DECLARATIONS"]

src/jacobian/domains/graph_optimization/invariant_bundle.py

@@ -7,6 +7,10 @@
 from jacobian.domains.graph_optimization.checkers import (
     GRAPH_INVARIANT_EXACT_REPLAY_CHECKERS,
 )
+from jacobian.domains.graph_optimization.graph6 import (
+    GRAPH6_CAPABILITIES,
+    GRAPH6_CHECKER_DECLARATIONS,
+)
 from jacobian.domains.graph_optimization.invariants import (
     EXACT_GRAPH_INVARIANT_CAPABILITIES,
 )
@@ -66,7 +70,7 @@ def build_graph_invariant_bundle() -> DomainBundle:
             ),
         ),
         backend_version=f"networkx-{NETWORKX_VERSION};sympy-{SYMPY_VERSION}",
-        capabilities=EXACT_GRAPH_INVARIANT_CAPABILITIES,
+        capabilities=(*GRAPH6_CAPABILITIES, *EXACT_GRAPH_INVARIANT_CAPABILITIES),
         diagnostics=DomainDiagnostics(
             invalid_request=CapabilityDiagnostic(
                 code="INVALID_GRAPH_INVARIANT_REQUEST",
@@ -75,5 +79,8 @@ def build_graph_invariant_bundle() -> DomainBundle:
                 hint="Supply a canonical simple graph with at most 32 vertices.",
             )
         ),
-        checker_declarations=GRAPH_INVARIANT_EXACT_REPLAY_CHECKERS,
+        checker_declarations=(
+            *GRAPH6_CHECKER_DECLARATIONS,
+            *GRAPH_INVARIANT_EXACT_REPLAY_CHECKERS,
+        ),
     )

src/jacobian/exact_domain_checkers.py

@@ -74,6 +74,7 @@
 _ENTRYPOINT_PROVIDER_RUNTIME_KEYS = {
     "jacobian_checkers.exact_domain_operations": "python-flint",
     "jacobian_checkers.graph_exact_operations": "finite-graph",
+    "jacobian_checkers.graph6": "graph6",
     "jacobian_checkers.exact_probability_operations": "finite-probability",
     "jacobian_checkers.recurrence_series": "combinatorics",
     "jacobian_checkers.additive_combinatorics": "combinatorics",
@@ -187,6 +188,15 @@ def install_exact_domain_checkers(
         "python-flint": exact_domain_checker_provider_runtime,
         "certified-snf": certified_snf_checker_provider_runtime,
         "finite-graph": graph_exact_checker_provider_runtime,
+        "graph6": partial(
+            source_provider_runtime,
+            "jacobian.graph6-checker",
+            version="1",
+            entrypoint="jacobian_checkers.graph6:check_graph6_decode",
+            install_tier=CapabilityInstallTier.T1,
+            license_id="MIT",
+            features=("standard-library-bitstream-replay", "clean-process-checker"),
+        ),
         "finite-probability": probability_exact_checker_provider_runtime,
         "combinatorics": combinatorics_exact_checker_provider_runtime,
         "poset": poset_exact_checker_provider_runtime,

src/jacobian/math/graphs/graph6.py

@@ -0,0 +1,97 @@
+"""Canonical small-order graph6 decoding."""
+
+from __future__ import annotations
+
+from hashlib import sha256
+from typing import Literal, Self
+
+from pydantic import Field, StrictInt, StrictStr, model_validator
+
+from jacobian.canonical import canonicalize_json
+from jacobian.contracts.base import ContractModel
+from jacobian.contracts.common import Sha256Digest
+
+
+class Graph6Edge(ContractModel):
+    first: StrictInt = Field(ge=0, le=62)
+    second: StrictInt = Field(ge=0, le=62)
+
+    @model_validator(mode="after")
+    def require_canonical_endpoints(self) -> Self:
+        if self.first >= self.second:
+            raise ValueError("graph6 edge endpoints must be strictly increasing")
+        return self
+
+
+class Graph6DecodeValue(ContractModel):
+    graph6: StrictStr = Field(min_length=1, max_length=352)
+    order: StrictInt = Field(ge=0, le=62)
+    edges: tuple[Graph6Edge, ...] = Field(max_length=1891)
+    degrees: tuple[StrictInt, ...] = Field(max_length=62)
+    graph_digest: Sha256Digest
+    format: Literal["GRAPH6_SMALL_ORDER"] = "GRAPH6_SMALL_ORDER"
+    bit_order: Literal["COLUMN_MAJOR_UPPER_TRIANGLE"] = (
+        "COLUMN_MAJOR_UPPER_TRIANGLE"
+    )
+
+    @model_validator(mode="after")
+    def bind_dimensions(self) -> Self:
+        if len(self.degrees) != self.order:
+            raise ValueError("graph6 degree sequence must match graph order")
+        pairs = tuple((edge.first, edge.second) for edge in self.edges)
+        if pairs != tuple(sorted(pairs)) or len(pairs) != len(set(pairs)):
+            raise ValueError("graph6 edges must be unique and sorted")
+        if any(edge.second >= self.order for edge in self.edges):
+            raise ValueError("graph6 edge endpoint exceeds graph order")
+        expected = [0] * self.order
+        for edge in self.edges:
+            expected[edge.first] += 1
+            expected[edge.second] += 1
+        if tuple(expected) != self.degrees:
+            raise ValueError("graph6 degree sequence does not match edges")
+        return self
+
+
+def decode_graph6(encoded: str) -> Graph6DecodeValue:
+    value = encoded[10:] if encoded.startswith(">>graph6<<") else encoded
+    if not value or value[0] in {":", "&"}:
+        raise ValueError("only standard graph6 is supported")
+    codes = [ord(character) - 63 for character in value]
+    if any(code < 0 or code > 63 for code in codes) or codes[0] == 63:
+        raise ValueError("graph6 payload is malformed or uses an extended header")
+    order = codes[0]
+    bit_count = order * (order - 1) // 2
+    if len(codes) != 1 + (bit_count + 5) // 6:
+        raise ValueError("graph6 payload length does not match its order header")
+    bits = [
+        (code >> shift) & 1
+        for code in codes[1:]
+        for shift in range(5, -1, -1)
+    ]
+    if any(bits[bit_count:]):
+        raise ValueError("unused graph6 padding bits must be zero")
+    pairs = [(first, second) for second in range(1, order) for first in range(second)]
+    edges = tuple(
+        Graph6Edge(first=first, second=second)
+        for first, second in sorted(
+            pair for pair, bit in zip(pairs, bits, strict=False) if bit
+        )
+    )
+    degrees = [0] * order
+    for edge in edges:
+        degrees[edge.first] += 1
+        degrees[edge.second] += 1
+    digest_payload = {
+        "order": order,
+        "edges": [[edge.first, edge.second] for edge in edges],
+    }
+    return Graph6DecodeValue(
+        graph6=value,
+        order=order,
+        edges=edges,
+        degrees=tuple(degrees),
+        graph_digest="sha256:" + sha256(canonicalize_json(digest_payload)).hexdigest(),
+    )
+
+
+__all__ = ["Graph6DecodeValue", "Graph6Edge", "decode_graph6"]

src/jacobian_checkers/graph6.py

@@ -0,0 +1,90 @@
+"""Independent graph6 replay using only the standard library."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from jacobian_checkers.bound_artifacts import bound_request
+
+
+def _reject(detail: str) -> dict[str, Any]:
+    return {
+        "accepted": False,
+        "conclusion": "UNKNOWN",
+        "arithmetic": "EXACT_INTEGER",
+        "method": "DIRECT_WITNESS",
+        "coverage": "NOT_APPLICABLE",
+        "detail": detail,
+    }
+
+
+def _accept(detail: str) -> dict[str, Any]:
+    return {
+        "accepted": True,
+        "conclusion": "TRUE",
+        "arithmetic": "EXACT_INTEGER",
+        "method": "DIRECT_WITNESS",
+        "coverage": "NOT_APPLICABLE",
+        "detail": detail,
+    }
+
+
+def check_graph6_decode(request: object) -> dict[str, Any]:
+    try:
+        source, result = bound_request(
+            request,
+            operation_id="graph.encoding.graph6.decode.compute",
+            witness_format="graph.graph6-decode.standard-library-v1",
+        )
+        if set(source) != {"graph6"} or not isinstance(source["graph6"], str):
+            raise ValueError("graph6 source is malformed")
+        value = source["graph6"]
+        value = value[10:] if value.startswith(">>graph6<<") else value
+        if not value or value[0] in {":", "&"}:
+            raise ValueError("unsupported graph encoding")
+        codes = [ord(character) - 63 for character in value]
+        if any(code < 0 or code > 63 for code in codes) or codes[0] == 63:
+            raise ValueError("malformed or extended graph6 encoding")
+        order = codes[0]
+        bit_count = order * (order - 1) // 2
+        if len(codes) != 1 + (bit_count + 5) // 6:
+            raise ValueError("graph6 length does not match order")
+        bits = [
+            (code >> shift) & 1
+            for code in codes[1:]
+            for shift in range(5, -1, -1)
+        ]
+        if any(bits[bit_count:]):
+            raise ValueError("graph6 padding bits are nonzero")
+        pairs = [(first, second) for second in range(1, order) for first in range(second)]
+        edges = sorted(pair for pair, bit in zip(pairs, bits, strict=False) if bit)
+        degrees = [0] * order
+        for first, second in edges:
+            degrees[first] += 1
+            degrees[second] += 1
+        digest_payload = json.dumps(
+            {"edges": [list(edge) for edge in edges], "order": order},
+            allow_nan=False,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        ).encode()
+        expected = {
+            "graph6": value,
+            "order": order,
+            "edges": [{"first": first, "second": second} for first, second in edges],
+            "degrees": degrees,
+            "graph_digest": "sha256:" + hashlib.sha256(digest_payload).hexdigest(),
+            "format": "GRAPH6_SMALL_ORDER",
+            "bit_order": "COLUMN_MAJOR_UPPER_TRIANGLE",
+        }
+        if result != expected:
+            return _reject("candidate does not match independent graph6 replay")
+        return _accept("independent graph6 bitstream replay accepted candidate")
+    except (KeyError, TypeError, ValueError, OverflowError):
+        return _reject("malformed, unsupported, or mismatched checker request")
+
+
+__all__ = ["check_graph6_decode"]