feat(composition): pass typed results to exact checkers (#1298)

* feat(composition): pass typed results to exact checkers

* test(evals): add matched typed handoff treatment

* test(verification): reject mismatched candidate references

* test(composition): wire value store in context fixture

* docs(mcp): disambiguate typed input binding

* style(checkers): sort current-main merge imports

* own Smith normal form values in the matrix domain

* fix matrix value export ordering

* fix(matrix): remove superseded Smith result model

---------

Co-authored-by: Kaoru0822 <aisakamimaki@gmail.com>

Author: morluto

benchmarks/config/schema-bound-selection-v1.json

@@ -0,0 +1,41 @@
+{
+  "schema_version": "2",
+  "suite_id": "schema-bound-selection-v1",
+  "cases": [
+    {
+      "case_id": "scalar-gcd",
+      "cue_level": "EXPLICIT",
+      "prompt": "Use the Jacobian MCP server. Discover or inspect the exact operation contract, then compute gcd(3918848, 1653264). Report the exact integer result. Do not use shell, Python, or mental arithmetic when Jacobian offers the operation.",
+      "expectation": "USE",
+      "expected_capability_ids": [
+        "integer.compute.gcd"
+      ]
+    },
+    {
+      "case_id": "nested-polynomial-gcd",
+      "cue_level": "EXPLICIT",
+      "prompt": "Use the Jacobian MCP server. Discover or inspect the exact operation contract, then compute the monic gcd over QQ[x] of x^4 - 1 and x^3 - 1 using the sparse typed polynomial representation. Report the exact polynomial result. Do not use shell, Python, or a CAS outside Jacobian.",
+      "expectation": "USE",
+      "expected_capability_ids": [
+        "polynomial.compute.gcd"
+      ]
+    },
+    {
+      "case_id": "smith-producer-checker",
+      "cue_level": "EXPLICIT",
+      "prompt": "Use the Jacobian MCP server to compute the Smith normal form of the integer matrix [[2,4],[6,8]], then independently verify that produced result with the linked exact replay verifier. Inspect exact contracts as needed. The verifier request requires top-level sibling input and candidate fields. Report the invariant factors and whether a verification record was produced. Do not use shell or Python.",
+      "expectation": "USE",
+      "expected_capability_ids": [
+        "matrix.normal_form.smith.compute",
+        "matrix.normal_form.smith.verify"
+      ],
+      "require_verified": true
+    },
+    {
+      "case_id": "negative-no-surface",
+      "cue_level": "LATENT",
+      "prompt": "Write one original two-line rhyming couplet about a quiet library. Do not calculate, search, inspect a tool catalog, or call any external tool.",
+      "expectation": "ABSTAIN"
+    }
+  ]
+}

benchmarks/config/typed-checker-handoff-v1.json

@@ -0,0 +1,41 @@
+{
+  "schema_version": "2",
+  "suite_id": "typed-checker-handoff-v1",
+  "cases": [
+    {
+      "case_id": "scalar-gcd",
+      "cue_level": "EXPLICIT",
+      "prompt": "Use the Jacobian MCP server. Discover or inspect the exact operation contract, then compute gcd(3918848, 1653264). Report the exact integer result. Do not use shell, Python, or mental arithmetic when Jacobian offers the operation.",
+      "expectation": "USE",
+      "expected_capability_ids": [
+        "integer.compute.gcd"
+      ]
+    },
+    {
+      "case_id": "nested-polynomial-gcd",
+      "cue_level": "EXPLICIT",
+      "prompt": "Use the Jacobian MCP server. Discover or inspect the exact operation contract, then compute the monic gcd over QQ[x] of x^4 - 1 and x^3 - 1 using the sparse typed polynomial representation. Report the exact polynomial result. Do not use shell, Python, or a CAS outside Jacobian.",
+      "expectation": "USE",
+      "expected_capability_ids": [
+        "polynomial.compute.gcd"
+      ]
+    },
+    {
+      "case_id": "smith-producer-checker",
+      "cue_level": "EXPLICIT",
+      "prompt": "Use the Jacobian MCP server to compute the Smith normal form of the integer matrix [[2,4],[6,8]], then independently verify that produced result with the exact replay verifier. Inspect exact contracts as needed. Use a declared runtime-local typed value reference to carry the producer result into the checker when that port exists; otherwise use the checker's inline candidate contract. Report the invariant factors and whether a verification record was produced. Do not use shell or Python.",
+      "expectation": "USE",
+      "expected_capability_ids": [
+        "matrix.normal_form.smith.compute",
+        "matrix.normal_form.smith.verify"
+      ],
+      "require_verified": true
+    },
+    {
+      "case_id": "negative-no-surface",
+      "cue_level": "LATENT",
+      "prompt": "Write one original two-line rhyming couplet about a quiet library. Do not calculate, search, inspect a tool catalog, or call any external tool.",
+      "expectation": "ABSTAIN"
+    }
+  ]
+}

docs/reference/capabilities/matrix/index.md

@@ -19,10 +19,10 @@ embed `RationalMatrix` or `IntegerMatrix` and apply their own 256-digit
 execution budget via `require_matrix_scalar_digits`. The shared matrix models
 themselves permit up to 32,768 canonical digits; each operation request
 tightens this to 256 decimal digits per scalar component before computation.
-Result models reuse the same shared types directly—`RrefResult.reduced_matrix`
-is a `RationalMatrix`, `SmithNormalFormResult.normal_form` is an
-`IntegerMatrix`, and so on—so producer and consumer share one canonical wire
-and persistence form without per-operation matrix schemas.
+Result models use the provider-independent domain values directly—`RrefResult.reduced_matrix`
+is a `RationalMatrix`, and `SmithNormalForm.normal_form` is an
+`IntegerMatrix`, and so on—so producer and consumer share typed values
+without per-operation matrix schemas.
 
 ## Conversion and kernel layer
 

docs/reference/domain-operation-library.md

@@ -194,6 +194,12 @@ identity, and runtime identity. Rejection is a checker verdict; interruption,
 timeout, provider failure, malformed output, or missing evidence is a
 non-conclusion and cannot create a record.
 
+An inline producer may expose its whole typed result through an output port and
+an exact checker may accept that value through a candidate input port. This
+changes only the runtime-local carrier: the checker still parses the assembled
+typed request once, independently replays the relation, and alone owns any
+verification record. A candidate reference never transfers producer authority.
+
 ## Values and publication
 
 Small bounded values remain inline. Use a request-local reference or durable

docs/reference/tools.md

@@ -92,6 +92,25 @@ reference:
 }
 ```
 
+The same carrier can avoid reserializing a producer's typed result into an
+independent checker request. For example, the Smith producer exposes its result
+as `output.value_refs.smith_form`, while its checker declares the `candidate`
+input port:
+
+```json
+{
+  "capability_id": "matrix.normal_form.smith.verify",
+  "payload": {"input": {"matrix": {"entries": [["2", "4"], ["6", "8"]]}}},
+  "inputs": {
+    "candidate": {"value_ref": "value://AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}
+  }
+}
+```
+
+The reference only carries the candidate value. The separate checker still
+validates the complete request and independently replays the relation before it
+can create a verification record.
+
 The runtime resolves declared inputs, assembles one request, parses it once,
 runs preflight, executes one semantic operation, checks the request/result
 postcondition, and then publishes the result. Unknown top-level arguments and

src/jacobian/adapters/mcp/guidance.py

@@ -66,6 +66,12 @@
 item's `input` object as the `payload`. Do not call math.run with an empty `payload`
 merely to discover required fields; the inspect result is the authoritative contract.
 
+When a completed output contains `value_refs`, an inspected consumer may declare a
+matching named `input_port`. Bind that opaque runtime-local reference through
+`inputs`; keep only the consumer's other request fields in `payload`, and do not
+repeat the port-bound field there. A value reference avoids retranscribing the typed
+value but carries no verification authority.
+
 Ordinary tools return calculations. Independent checking uses a separate checker
 tool ID (for example `polynomial.identity.verify`), not a switch on the producer.
 Failed, cancelled, timed-out, or incomplete runs are not mathematical conclusions.

src/jacobian/contracts/matrix_operations.py

@@ -2,12 +2,10 @@
 
 from __future__ import annotations
 
-from itertools import pairwise
 from typing import Annotated, Literal, Self
 
 from pydantic import Field, StrictInt, field_validator, model_validator
 
-from jacobian.canonical import parse_canonical_integer
 from jacobian.contracts.exact import CanonicalInteger, CanonicalRational
 from jacobian.contracts.matrices import (
     MAX_MATRIX_DIMENSION,
@@ -263,53 +261,6 @@ def require_dense_monic_coefficients(self) -> Self:
         return self
 
 
-class SmithNormalFormResult(ContractModel):
-    normal_form: IntegerMatrix
-    rank: int = Field(ge=0, le=MAX_MATRIX_DIMENSION)
-    invariant_factors: tuple[CanonicalInteger, ...] = Field(
-        max_length=MAX_MATRIX_DIMENSION
-    )
-    transformation_available: Literal[False] = False
-    convention: Literal["POSITIVE_DIVISIBILITY_DIAGONAL"] = (
-        "POSITIVE_DIVISIBILITY_DIAGONAL"
-    )
-
-    @model_validator(mode="after")
-    def require_invariant_factor_chain(self) -> Self:
-        if len(self.invariant_factors) != self.rank:
-            raise ValueError("nonzero invariant factor count must equal rank")
-        rows = len(self.normal_form.entries)
-        columns = len(self.normal_form.entries[0])
-        if self.rank > min(rows, columns):
-            raise ValueError("Smith rank cannot exceed the matrix dimensions")
-        factors = tuple(
-            parse_canonical_integer(value) for value in self.invariant_factors
-        )
-        if any(value <= 0 for value in factors):
-            raise ValueError("Smith invariant factors must be positive")
-        if any(right % left != 0 for left, right in pairwise(factors)):
-            raise ValueError("each Smith invariant factor must divide the next")
-        for row, entries in enumerate(self.normal_form.entries):
-            for column, value in enumerate(entries):
-                expected = factors[row] if row == column and row < self.rank else 0
-                if parse_canonical_integer(value) != expected:
-                    raise ValueError(
-                        "Smith normal form must contain its positive invariant "
-                        "factors on the leading diagonal and zero elsewhere"
-                    )
-        return self
-
-    @field_validator("invariant_factors")
-    @classmethod
-    def require_bounded_invariant_factors(
-        cls,
-        values: tuple[CanonicalInteger, ...],
-    ) -> tuple[CanonicalInteger, ...]:
-        for value in values:
-            _check_integer_digits(value, maximum=MAX_MATRIX_SCALAR_DIGITS)
-        return values
-
-
 class MatrixInverseResult(ContractModel):
     inverse: RationalMatrix
     convention: Literal["TWO_SIDED_INVERSE_OVER_QQ"] = "TWO_SIDED_INVERSE_OVER_QQ"

src/jacobian/domains/matrix_lattice/capabilities.py

@@ -1,6 +1,7 @@
 """Exact matrix capability declarations."""
 
 from collections.abc import Callable
+from typing import Any
 
 from pydantic import ValidationError
 
@@ -25,7 +26,6 @@
     RationalMatrixProductRequest,
     RationalMatrixRequest,
     RrefResult,
-    SmithNormalFormResult,
     SquareIntegerMatrixRequest,
     SquareRationalMatrixRequest,
 )
@@ -44,7 +44,9 @@
     compute_smith_normal_form,
     compute_trace,
 )
+from jacobian.math.matrices.values import SmithNormalForm
 from jacobian.operation_bindings import InstalledOperation, inline_operation
+from jacobian.operation_ports import OutputPort
 from jacobian.operations import (
     OperationAbortError,
     OperationRefusalError,
@@ -64,6 +66,7 @@ def matrix_operation[
     operation: Callable[[RequestT], ResultT],
     *tags: str,
     invocation_examples: tuple[CapabilityInvocationExample, ...] = (),
+    output_ports: tuple[OutputPort[Any], ...] = (),
     version: str = "1",
 ) -> InstalledOperation[RequestT, ResultT]:
     def implementation(request: RequestT) -> ResultT:
@@ -106,7 +109,8 @@ def implementation(request: RequestT) -> ResultT:
             execute=implementation,
             tags=tags,
             invocation_examples=invocation_examples,
-        )
+        ),
+        output_ports=output_ports,
     )
 
 
@@ -422,7 +426,7 @@ def implementation(request: RequestT) -> ResultT:
             "unavailable left or right transformations."
         ),
         IntegerMatrixRequest,
-        SmithNormalFormResult,
+        SmithNormalForm,
         compute_smith_normal_form,
         "matrix",
         "smith-normal-form",
@@ -434,5 +438,7 @@ def implementation(request: RequestT) -> ResultT:
                 {"matrix": {"entries": [["2", "4"], ["6", "8"]]}},
             ),
         ),
+        output_ports=(OutputPort(name="smith_form", value_type=SmithNormalForm),),
+        version="2",
     ),
 )

src/jacobian/domains/matrix_lattice/conversions.py

@@ -8,13 +8,15 @@
 from jacobian.contracts.exact import CanonicalRational
 from jacobian.contracts.matrices import IntegerMatrix, RationalMatrix
 from jacobian.contracts.matrix_operations import DeterminantRationalMatrix
+from jacobian.math.matrices.values import SmithNormalForm
 
 __all__ = [
     "integer_matrix_from_sympy",
     "integer_matrix_to_sympy",
     "rational_from_sympy",
     "rational_matrix_from_sympy",
     "rational_matrix_to_sympy",
+    "smith_normal_form_from_sympy",
 ]
 
 
@@ -76,3 +78,31 @@ def integer_matrix_from_sympy(matrix: Any) -> IntegerMatrix:
             for row in range(matrix.rows)
         )
     )
+
+
+def smith_normal_form_from_sympy(matrix: Any) -> SmithNormalForm:
+    """Convert one SymPy Smith form into the provider-independent value."""
+
+    import sympy
+
+    if not isinstance(matrix, sympy.MatrixBase):
+        raise TypeError("Smith backend returned a non-matrix value")
+    diagonal_count = min(matrix.rows, matrix.cols)
+    diagonal = tuple(int(matrix[index, index]) for index in range(diagonal_count))
+    rank = next(
+        (index for index, value in enumerate(diagonal) if value == 0),
+        diagonal_count,
+    )
+    if any(diagonal[index] != 0 for index in range(rank, diagonal_count)):
+        raise ValueError("Smith backend returned a nonzero factor after a zero")
+    invariant_factors = tuple(abs(value) for value in diagonal[:rank])
+    canonical = sympy.zeros(matrix.rows, matrix.cols)
+    for index, value in enumerate(invariant_factors):
+        canonical[index, index] = value
+    return SmithNormalForm(
+        normal_form=integer_matrix_from_sympy(canonical),
+        rank=rank,
+        invariant_factors=tuple(
+            format_canonical_integer(value) for value in invariant_factors
+        ),
+    )

src/jacobian/domains/matrix_lattice/operations.py

@@ -21,12 +21,12 @@
     RationalMatrixProductRequest,
     RationalMatrixRequest,
     RrefResult,
-    SmithNormalFormResult,
     SquareIntegerMatrixRequest,
     SquareRationalMatrixRequest,
 )
 from jacobian.domains.matrix_lattice import conversions
 from jacobian.math import matrices
+from jacobian.math.matrices.values import SmithNormalForm
 
 
 def compute_determinant(
@@ -108,31 +108,11 @@ def compute_characteristic_polynomial(
 
 def compute_smith_normal_form(
     request: IntegerMatrixRequest,
-) -> SmithNormalFormResult:
-    import sympy
-
+) -> SmithNormalForm:
     raw = matrices.smith_normal_form(
         conversions.integer_matrix_to_sympy(request.matrix)
     )
-    diagonal_count = min(raw.rows, raw.cols)
-    diagonal = tuple(int(raw[index, index]) for index in range(diagonal_count))
-    rank = next(
-        (index for index, value in enumerate(diagonal) if value == 0),
-        diagonal_count,
-    )
-    if any(diagonal[index] != 0 for index in range(rank, diagonal_count)):
-        raise RuntimeError("Smith backend returned a nonzero factor after a zero")
-    invariant_factors = tuple(abs(value) for value in diagonal[:rank])
-    canonical = sympy.zeros(raw.rows, raw.cols)
-    for index, value in enumerate(invariant_factors):
-        canonical[index, index] = value
-    return SmithNormalFormResult(
-        normal_form=conversions.integer_matrix_from_sympy(canonical),
-        rank=rank,
-        invariant_factors=tuple(
-            format_canonical_integer(value) for value in invariant_factors
-        ),
-    )
+    return conversions.smith_normal_form_from_sympy(raw)
 
 
 def compute_inverse(request: SquareIntegerMatrixRequest) -> MatrixInverseResult: