ut3_absorb_weights
==================

.. py:function:: t3toolbox.backend.ut3_operations.ut3_absorb_weights(x, weights)

   .. code-block:: python

      def ut3_absorb_weights(
              x:       UT3Data,         # (tucker_supercore, tt_supercore, shape, masks)
              weights: UT3WeightsData,  # (tucker_weight_supercore, tt_weight_supercore, masks)
      ) -> UT3Data:                     # the weighted train: same shape, same masks (absorb preserves both)


   Contract diagonal edge weights into a uniform Tucker tensor train's supercores (shape-preserving).

   The uniform twin of ``t3_absorb_weights``, with the same side-convention, but vectorized over the
   leading ``(d,)`` instead of looping the cores:

   - **Tucker weights -> the Tucker supercore** (its rank leg ``n``).
   - **TT bond weights leftward**: bond ``r(k+1)`` into core ``k``'s right leg; the leftmost boundary
     bond ``r0`` (which has no left neighbour) goes **rightward** into core ``0``'s left leg instead. So
     each of the ``d+1`` bonds is absorbed exactly once.

   **No entry masking, deliberately -- absorb is garbage-transparent.** It is a *pointwise scale along
   each edge axis*, not a reduction: real slot ``i`` of the output depends only on slot ``i`` of the core
   and slot ``i`` of the weight, so garbage can never mix into a real slot. Garbage padding in gives
   garbage padding out, which the equivalence contract declares don't-care
   (``docs/uniform_equivalence_contract.md``). Do not add a defensive entry-mask: it would be dead work,
   and masking is a separate concern from weighting (``docs/contributor/weighted_internals.md`` §2).

   **Precondition (structural; NOT enforced here):** ``weights``' masks must equal ``x``'s masks --
   :py:func:`ut3_weights_consistent`. Ragged catches a rank mismatch as a loud einsum shape error, but
   uniform pads both to the common ``(n, r)``, so a mismatch is **silent and corrupting** (a weight whose
   mask calls slot ``i`` padding carries a canonical zero there, and absorbing it would zero a *real*
   slot of ``x``). The frontend enforces it; a raw-``.data`` user should call the predicate first. This
   is the same precondition uniform adds to variation add/sub (``docs/uniform_masks_vs_ranks.md``).