docs(function): define forward-compatible version projection (#4863)

Clarify `FunctionVersion` forward compatibility: unknown top-level
fields are accepted during decoding and omitted from canonical JSON,
while all defined fields and the open `image.descriptor` content retain
their values. Extend the existing Rust and Python canonical round-trip
tests to assert the complete projected object, including future
discriminator values.

This documents and tests the existing behavior; it does not change
runtime serialization or promise lossless retention of unknown top-level
fields.

Related: ENT-2176.

python/python/lancedb/functions.py

@@ -469,6 +469,12 @@ _ObjectVersion = Annotated[
 class FunctionVersion(_RemoteValue):
     """A pinned object revision, independent of its executable image digest.
 
+    Unknown top-level fields from newer servers are accepted for forward
+    decoding, but they are not exposed on this value and are omitted from
+    ``to_canonical_json()``. Known fields retain their complete values, while
+    unknown fields inside the open ``image.descriptor`` mapping remain
+    available.
+
     ``name`` and ``namespace_path`` are the Function's parts, as a
     [SecretReference][lancedb.functions.SecretReference] carries a Secret's;
     they are what [get_function][lancedb.db.DBConnection.get_function] takes.

python/python/tests/test_first_class_function_slice1.py

@@ -301,10 +301,15 @@ def test_unknown_fields_and_discriminators_are_forward_decodable():
 
     version = FunctionVersion.from_json(json.dumps(value))
     assert version.image.descriptor["future_interface"] == {"kind": "wasm"}
-    assert json.loads(version.to_canonical_json())["image"]["descriptor"][
-        "future_interface"
-    ] == {"kind": "wasm"}
     assert version.signature.output.kind == "future_output_shape"
+    assert not hasattr(version, "future_version_metadata")
+
+    canonical = json.loads(version.to_canonical_json())
+    expected = json.loads(fixture("remote_function_version.canonical.json"))
+    expected["image"]["descriptor"]["future_interface"] = {"kind": "wasm"}
+    expected["signature"]["output"]["kind"] = "future_output_shape"
+    assert canonical == expected
+    assert "future_version_metadata" not in canonical
 
 
 def test_function_application_uses_rename_columns_only():