Call-form consumers declare no eager dtype coercion (`tf.matmul`, `tf.tensordot`, `tf.einsum`, function-form elementwise operations).

[khatchad]

Context

The parameter dtype coercion machinery of #828 and #829 rewrites a parameter's reported dtype to the one its consumers impose eagerly. The declared set is currently exactly the operator-spelled elementwise operations: ElementWiseOperation implements OperandDTypeCoercing, and the walk reaches it through SSABinaryOpInstruction uses. Every other consumer that takes a second operand falls into the unaccounted-consumer guard, which declines the whole parameter to its fed dtype by design; the guard's own comment names tf.matmul and the tensordot/einsum shapes as the known coverage debt.

Witness

import numpy as np
import tensorflow as tf

M = tf.Variable(tf.zeros([2, 2]))  # float32

def matmuled(x):
    return tf.reduce_sum(tf.matmul(M, x))

matmuled(np.array([[1.5, 2.5], [3.5, 4.5]]))  # float64 fed; converts at the matmul

Eagerly, tf.matmul converts the non-tensor operand to its tensor partner's dtype, so the body computes with float32. The analysis reports the fed float64: the tf.matmul consumer declares no coercion, the parameter is declined by the unaccounted guard, and the fed dtype is kept. A client writing an input signature from the reported dtype names a dtype no op in the body computes with, and the resulting declaration breaks the function that ran fine undecorated (the consumer-side report is ponder-lab/Hybridize-Functions-Refactoring#907).

Expected

The call-form coercing families declared under the same eager criterion the operator forms use: an op that converts a non-tensor operand through convert_to_tensor against its tensor partner's dtype imposes that dtype on a parameter operand. The tensor-tensor mismatch case raises eagerly and so is excluded by the premise that the undecorated program ran, exactly as the OperandDTypeCoercing contract already states for chained consumers.

Scope

Beyond tf.matmul, tf.tensordot, and tf.einsum, the function-form spellings of the already-declared elementwise operations sit in the same undeclared position: the spelling tf.multiply(V, x) is a call, not a binary op instruction, so only the operator spelling V * x is covered today. The same family includes tf.add, tf.subtract, tf.divide, tf.pow, tf.maximum, tf.minimum, and tf.squared_difference. The unaccounted-consumer guard keeps all of these safe (declined to the fed dtype) rather than wrong, so this is a coverage gap, not a soundness bug.

[khatchad]

Canonical Family Enumeration

This issue is the single home for the coercing-family enumeration; the consumer-side recognizer of ponder-lab/Hybridize-Functions-Refactoring#908 mirrors this set, and additions land here first so the two sides cannot drift.

Declared today, operator spellings only: +, -, *, / (the SSABinaryOpInstruction ADD/SUB/MUL/DIV arms). The % and ** operators are recorded TODO gaps in TensorGeneratorFactory, so even their operator spellings declare nothing yet.

Call-form family to declare, by the criterion (the op eagerly converts a non-tensor operand through convert_to_tensor against its tensor partner's dtype): matmul, tensordot, einsum, matvec, add, subtract, multiply, divide, truediv, floordiv, mod (floormod), pow, maximum, minimum, squared_difference, divide_no_nan, multiply_no_nan. The tf.math and tf.linalg aliases arrive with the plain spellings under the same last name segment.

One arity note: the first positional argument of einsum is the equation string, so a two-operand einsum carries three arguments, and a recognizer that declines any call beyond a callee plus two operands will permanently decline it rather than recognize it. Declining is safe (the parameter keeps its fed dtype); recognizing it requires treating the equation slot specially.

[khatchad]

Correction: tensordot and matvec Enforce Equality Rather Than Coerce

Measurement on TF 2.9.3 (from the consumer-side fix work) shows two names in the enumeration above do not meet the criterion. With a float32 tensor partner and a float64 non-tensor operand:

tf.multiply(V32, X64)        -> float32   (convert_to_tensor with the partner's dtype as hint)
tf.matmul(M32, X64)          -> float32
tf.einsum("ij,jk->ik", ...)  -> float32
tf.tensordot(V32, X64, 1)    -> InvalidArgumentError
tf.linalg.matvec(M32, x64)   -> InvalidArgumentError

The same holds with a Python list operand, so it is not a numpy artifact: tensordot and matvec convert the non-tensor operand WITHOUT the partner's dtype as a hint and then raise on the mismatch.

The corrected classification: tensordot and matvec are EQUALITY-ENFORCING consumers, not coercing ones. For the signature question the two classes converge on the same imposition: a program that runs cannot have carried a mismatch through an equality-enforcing consumer (the mismatch raises eagerly, whether the operand arrived as a tensor or through the unhinted default conversion), so the operand's eager-effective dtype at that consumer EQUALS the partner's. Declaring the partner's dtype is therefore still the sound account, and strictly better than leaving them unaccounted, which would decline the whole parameter and discard the other consumers' collected coercions. What changes is the rationale recorded with the declaration: conversion for the coercing family, run-premise equality for these two.

The coercing family stands as listed above minus these two; tensordot and matvec move to this equality-enforcing note.