feat(composition): pass typed results to exact checkers

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/domain-operation-library.md

@@ -192,6 +192,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

@@ -64,6 +64,12 @@
 `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/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
 
@@ -45,6 +46,7 @@
     compute_trace,
 )
 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,
     )
 
 
@@ -434,5 +438,7 @@ def implementation(request: RequestT) -> ResultT:
                 {"matrix": {"entries": [["2", "4"], ["6", "8"]]}},
             ),
         ),
+        output_ports=(OutputPort(name="smith_form", value_type=SmithNormalFormResult),),
+        version="2",
     ),
 )

src/jacobian/exact_domain_checkers.py

@@ -11,7 +11,11 @@
 
 from jacobian.artifacts import ArtifactService
 from jacobian.capability_adapters import CapabilityAdapter
-from jacobian.capability_errors import CapabilityError, CapabilityInvocationError
+from jacobian.capability_errors import (
+    CapabilityError,
+    CapabilityInvocationError,
+    enriched_invalid_request,
+)
 from jacobian.checker_artifacts import put_witness_envelope
 from jacobian.checker_identity import batch_checker_manifest_measurement
 from jacobian.checker_installation import CheckerInstaller
@@ -23,6 +27,7 @@
     CapabilityProviderAvailability,
     CapabilityProviderRuntime,
     CapabilityRequest,
+    CapabilityValuePort,
 )
 from jacobian.contracts.checkers import EvidenceKind
 from jacobian.contracts.evidence import EvidenceBindings, WitnessEnvelope
@@ -41,6 +46,7 @@
 from jacobian.domain_bundles import DomainBundle
 from jacobian.operation_bindings import DurablePublication
 from jacobian.operation_installation import InstalledDomainBundle
+from jacobian.operation_ports import InputPort
 from jacobian.operation_projection import OperationProjection
 from jacobian.operation_publication import PublishedOperation
 from jacobian.operations import Completed, Failed
@@ -53,6 +59,7 @@
 from jacobian.storage.models import StoredArtifact
 from jacobian.storage.repository import ArtifactRepository
 from jacobian.validation_diagnostics import bounded_validation_exception_message
+from jacobian.value_references import ValueReferenceError, ValueReferenceStore
 from jacobian.verification.service import VerificationService
 
 _LOGGER = logging.getLogger(__name__)
@@ -276,6 +283,7 @@ def install_exact_domain_verification(
     store: ArtifactRepository,
     schemas: SchemaRegistry,
     artifacts: ArtifactService,
+    values: ValueReferenceStore,
     verification: VerificationService,
     checkers: CheckerRegistry,
     *,
@@ -325,6 +333,16 @@ def install_exact_domain_verification(
         for operation in bundle.capabilities
         if isinstance(operation.publication, DurablePublication)
     }
+    referenceable_results = {
+        operation.spec.operation_id: operation.spec.result_type
+        for bundle, _installed_bundle in bundles.values()
+        for operation in bundle.capabilities
+        if operation.output_ports
+        and any(
+            port.value_type is operation.spec.result_type
+            for port in operation.output_ports
+        )
+    }
     for installed_bundle, declaration in _available_declaration_bundles(bundles):
         if declaration.capability_id not in installed_bundle.result_schema_uris:
             continue
@@ -342,12 +360,16 @@ def install_exact_domain_verification(
                 store=store,
                 schemas=schemas,
                 artifacts=artifacts,
+                values=values,
                 verification=verification,
                 witness_schema_uri=witness_schema_uri,
                 provider_runtime=installation.provider_runtimes[
                     installation.declaration_providers[declaration.capability_id]
                 ],
                 stored_result_input=declaration.capability_id in stored_producers,
+                candidate_value_type=referenceable_results.get(
+                    declaration.capability_id
+                ),
             )
         )
     return tuple(adapters), installation
@@ -437,14 +459,17 @@ def __init__(
         store: ArtifactRepository,
         schemas: SchemaRegistry,
         artifacts: ArtifactService,
+        values: ValueReferenceStore,
         verification: VerificationService,
         witness_schema_uri: str,
         provider_runtime: CapabilityProviderRuntime,
         stored_result_input: bool,
+        candidate_value_type: type[ContractModel] | None,
     ) -> None:
         self.store = store
         self.schemas = schemas
         self.artifacts = artifacts
+        self.values = values
         self.verification = verification
         self.declaration = declaration
         self.witness_schema_uri = witness_schema_uri
@@ -454,6 +479,15 @@ def __init__(
             declaration.declaration.request_model,
             declaration.result_model,
         ]
+        self.candidate_port = (
+            InputPort(
+                name="candidate",
+                value_type=candidate_value_type,
+                request_field="candidate",
+            )
+            if candidate_value_type is not None and not stored_result_input
+            else None
+        )
         verification_capability_id = declaration.declaration.verification_capability_id
         verification_title = declaration.declaration.verification_title
         verification_description = declaration.declaration.verification_description
@@ -467,7 +501,7 @@ def __init__(
             )
         self._descriptor = CapabilityDescriptor(
             capability_id=verification_capability_id,
-            version="1",
+            version="2" if self.candidate_port is not None else "1",
             title=verification_title,
             description=verification_description,
             provider=provider_runtime.provider,
@@ -487,8 +521,20 @@ def __init__(
             accepted_artifact_types=(
                 (declaration.result_schema_uri,) if stored_result_input else ()
             ),
+            input_ports=(
+                (
+                    CapabilityValuePort(
+                        name=self.candidate_port.name,
+                        value_type=self.candidate_port.value_type.__name__,
+                    ),
+                )
+                if self.candidate_port is not None
+                else ()
+            ),
         )
 
+    typed_input: Literal[True] = True
+
     @property
     def descriptor(self) -> CapabilityDescriptor:
         return self._descriptor
@@ -767,7 +813,21 @@ def _validated_inline_payloads(
     ) -> tuple[dict[str, object], dict[str, object]]:
         declaration = self.declaration
         try:
-            validated = self.input_model.model_validate(request.input)
+            payload = request.input
+            if request.inputs:
+                if self.candidate_port is None:
+                    raise ValueError("this exact checker declares no value inputs")
+                unknown = sorted(set(request.inputs) - {self.candidate_port.name})
+                if unknown:
+                    raise ValueError(
+                        "unknown exact-checker input port: " + ", ".join(unknown)
+                    )
+                candidate = self.values.resolve(
+                    request.inputs[self.candidate_port.name],
+                    self.candidate_port.value_type,
+                )
+                payload = self.candidate_port.bind_to_request(payload, candidate)
+            validated = self.input_model.model_validate(payload)
             normalized_input = self.schemas.validate(
                 declaration.input_schema_uri,
                 validated.input.model_dump(mode="json"),
@@ -776,9 +836,23 @@ def _validated_inline_payloads(
                 declaration.result_schema_uri,
                 validated.candidate.model_dump(mode="json"),
             )
-        except (SchemaRegistryError, ValidationError, ValueError) as exc:
-            raise CapabilityInvocationError(
-                CapabilityDiagnostic(
+        except (
+            SchemaRegistryError,
+            ValidationError,
+            ValueError,
+            ValueReferenceError,
+        ) as exc:
+            diagnostic = (
+                enriched_invalid_request(
+                    CapabilityDiagnostic(
+                        code="INVALID_REQUEST",
+                        stage="capability_input_validation",
+                        message="The capability request is invalid.",
+                    ),
+                    exc,
+                )
+                if isinstance(exc, ValidationError)
+                else CapabilityDiagnostic(
                     code="INVALID_EXACT_DOMAIN_INPUT",
                     stage="request_validation",
                     message=bounded_validation_exception_message(exc),
@@ -787,7 +861,8 @@ def _validated_inline_payloads(
                         "candidate must satisfy its result contract."
                     ),
                 )
-            ) from exc
+            )
+            raise CapabilityInvocationError(diagnostic) from exc
         return normalized_input, normalized_candidate
 
     def _resolve_stored_result(