x4d-devkit 0.43.0rc4__tar.gz → 0.44.0rc1__tar.gz

{x4d_devkit-0.43.0rc4/x4d_devkit.egg-info → x4d_devkit-0.44.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.43.0rc4
+Version: 0.44.0rc1
 Summary: Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation
 Author: windzu
 License-Expression: Apache-2.0
@@ -264,8 +264,8 @@ identity manifests, and update plans use one schema field only:
 `clip_label_schema` are not aliases and are rejected. A ready platform record
 without the complete identity is also rejected.
 
-`x4d-devkit dataset inspect` writes `x4d-remote-identity-v6`, and
-`x4d-devkit dataset diff` writes `x4d-update-plan-v8`. The v8 plan records the
+`x4d-devkit dataset inspect` writes `x4d-remote-identity-v7`, and
+`x4d-devkit dataset diff` writes `x4d-update-plan-v9`. The v8 plan records the
 requested materialization policy, each cache's reviewed samples/sweeps
 materialization revisions, and every Clip's reviewed target and local
 predecessor identities.

{x4d_devkit-0.43.0rc4 → x4d_devkit-0.44.0rc1}/README.md

@@ -221,8 +221,8 @@ identity manifests, and update plans use one schema field only:
 `clip_label_schema` are not aliases and are rejected. A ready platform record
 without the complete identity is also rejected.
 
-`x4d-devkit dataset inspect` writes `x4d-remote-identity-v6`, and
-`x4d-devkit dataset diff` writes `x4d-update-plan-v8`. The v8 plan records the
+`x4d-devkit dataset inspect` writes `x4d-remote-identity-v7`, and
+`x4d-devkit dataset diff` writes `x4d-update-plan-v9`. The v8 plan records the
 requested materialization policy, each cache's reviewed samples/sweeps
 materialization revisions, and every Clip's reviewed target and local
 predecessor identities.

{x4d_devkit-0.43.0rc4 → x4d_devkit-0.44.0rc1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.43.0rc4"
+version = "0.44.0rc1"
 description = "Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation"
 readme = "README.md"
 license = "Apache-2.0"

{x4d_devkit-0.43.0rc4 → x4d_devkit-0.44.0rc1}/tests/test_boundary.py

@@ -77,6 +77,11 @@ def test_top_level_exports_only_stable_sdk_surface():
 
     assert set(x4d_devkit.__all__) == {
         "__version__",
+        "VECTOR_MAP_CONTRACT_VERSION",
+        "VectorMapDocument",
+        "parse_vector_map",
+        "parse_vector_map_change",
+        "vector_map_geometry_rules",
         "ANNOTATION_CONTRACT_VERSION",
         "CLEAN_BASEMAP_CONTRACT_VERSION",
         "CleanBasemapManifest",

{x4d_devkit-0.43.0rc4 → x4d_devkit-0.44.0rc1}/tests/test_current_state.py

@@ -31,6 +31,7 @@ def _identity(**overrides):
         "pose_revision": "pose",
         "annotation_revision": current_work_session_payload()["annotation_revision"],
         "semantic_scene_revision": None,
+        "vector_map_revision": None,
         "label_schema": schema_identity(),
         "business_metadata_revision": "business-metadata",
         "clip_schema_version": "0.17",
@@ -209,6 +210,7 @@ def test_clip_identity_direct_constructor_requires_explicit_pose_revision():
         label_schema=label_schema,
         pose_revision=None,
         semantic_scene_revision=None,
+        vector_map_revision=None,
     )
     assert identity.to_dict()["pose_revision"] is None
 

{x4d_devkit-0.43.0rc4 → x4d_devkit-0.44.0rc1}/tests/test_dataset_identity.py

@@ -46,6 +46,7 @@ def _identity(clip_id: str = "clip-a", **overrides):
         "pose_revision": "sha256:pose",
         "annotation_revision": "sha256:annotation",
         "semantic_scene_revision": None,
+        "vector_map_revision": None,
         "label_schema": schema_identity(),
         "business_metadata_revision": "sha256:business-metadata",
         "clip_schema_version": "0.17",
@@ -289,6 +290,7 @@ def test_update_plan_maps_each_change_to_independent_portable_action():
         "refresh_pose": ["clip-a"],
         "refresh_annotation": ["clip-a"],
         "refresh_semantic_scene": [],
+        "refresh_vector_map": [],
         "refresh_label_schema": ["clip-a"],
         "refresh_business_metadata": ["clip-a"],
         "rematerialize_clip": [],
@@ -459,6 +461,7 @@ def _local_from_work_session(payload):
                 "pose_revision",
                 "annotation_revision",
                 "semantic_scene_revision",
+                "vector_map_revision",
                 "label_schema",
                 "business_metadata_revision",
                 "clip_schema_version",
@@ -855,7 +858,7 @@ def test_sync_composes_schema_and_annotation_into_one_clip_update(tmp_path):
     result = sync_update_plan(client, plan=plan, data_root=tmp_path, workers=1)
 
     assert result["schema_version"] == SYNC_RESULT_SCHEMA_VERSION
-    assert result["schema_version"] == "x4d-sync-result-v8"
+    assert result["schema_version"] == "x4d-sync-result-v9"
     assert result["source_transfer"] == {
         "planned_objects": 0,
         "planned_bytes": 0,

{x4d_devkit-0.43.0rc4 → x4d_devkit-0.44.0rc1}/tests/test_inference_schemas.py

@@ -106,6 +106,7 @@ def test_source_identity_projects_only_pure_inference_dependencies():
             "pose_revision": "pose-1",
             "annotation_revision": _digest("a"),
             "semantic_scene_revision": _digest("d"),
+            "vector_map_revision": None,
             "label_schema": schema_identity(),
             "clip_schema_version": "0.17",
             "ready": True,

{x4d_devkit-0.43.0rc4 → x4d_devkit-0.44.0rc1}/tests/test_label_schemas.py

@@ -282,6 +282,7 @@ def test_batch_resolution_deduplicates_by_task_free_binding():
             "pose_revision": "pose-a",
                 "annotation_revision": "ann-a",
                 "semantic_scene_revision": None,
+                "vector_map_revision": None,
             "business_metadata_revision": "business-a",
             "label_schema": identity,
             "clip_schema_version": "0.17",
@@ -298,6 +299,7 @@ def test_batch_resolution_deduplicates_by_task_free_binding():
             "pose_revision": "pose-b",
                 "annotation_revision": "ann-b",
                 "semantic_scene_revision": None,
+                "vector_map_revision": None,
             "business_metadata_revision": "business-b",
             "label_schema": identity,
             "clip_schema_version": "0.17",

{x4d_devkit-0.43.0rc4 → x4d_devkit-0.44.0rc1}/tests/test_sdk_api.py

@@ -11,7 +11,7 @@ from x4d_devkit.eval.matching import MetricData
 
 
 def test_package_version_is_current_release():
-    assert x4d_devkit.__version__ == "0.43.0rc4"
+    assert x4d_devkit.__version__ == "0.44.0rc1"
 
 
 def test_loader_exposes_and_enforces_only_current_schema(tmp_path):

x4d_devkit-0.44.0rc1/tests/test_vector_map.py

@@ -0,0 +1,119 @@
+import copy
+import pytest
+
+from tests.vector_map_fixtures import document, map_schema, map_schema_body
+from tests.test_vector_map_geometry import square
+from x4d_devkit.label_schema import parse_label_schema_body
+from x4d_devkit.vector_map import parse_vector_map, parse_vector_map_change
+
+
+def parse(value):
+    return parse_vector_map(value, map_schema(), clip_id="clip-a")
+
+
+def test_shared_boundaries_and_directed_neighbor_survive_canonical_roundtrip():
+    value = document()
+    parsed = parse(value)
+    assert parsed.to_dict() == value
+    assert parse(parsed).revision == parsed.revision
+    value["features"][0]["geometry"]["coordinates"][0][2] = 100
+    assert parsed.to_dict()["features"][0]["geometry"]["coordinates"][0][2] == 2
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        "opposite",
+        "swapped",
+        "range",
+        "dangling",
+        "duplicate",
+        "foreign_clip",
+        "wrong_frame",
+        "schema",
+    ],
+)
+def test_invalid_native_references_geometry_or_identity_fail_closed(change):
+    value = document()
+    if change == "opposite":
+        value["lane_segments"][0]["right_boundary"]["reverse"] = True
+    elif change == "swapped":
+        lane = value["lane_segments"][0]
+        lane["left_boundary"], lane["right_boundary"] = (
+            lane["right_boundary"],
+            lane["left_boundary"],
+        )
+    elif change == "range":
+        value["lane_segments"][0]["left_boundary"]["end_s_m"] = 100
+    elif change == "dangling":
+        value["relations"][0]["to_token"] = "missing"
+    elif change == "duplicate":
+        value["relations"].append({**value["relations"][0], "token": "another"})
+    elif change == "foreign_clip":
+        value["clip_id"] = "other"
+    elif change == "wrong_frame":
+        value["frame_id"] = "world"
+    elif change == "schema":
+        value["provenance"]["label_schema_fingerprint"] = "sha256:" + "0" * 64
+    with pytest.raises(ValueError):
+        parse(value)
+
+
+def test_explicit_successor_cycle_is_legal_without_inferred_reciprocal_edges():
+    value = document()
+    value["relations"] = [
+        {
+            "token": "cycle",
+            "kind": "lane_successor",
+            "from_token": "lane-a",
+            "to_token": "lane-a",
+            "side": None,
+            "source_tokens": [],
+        }
+    ]
+    assert len(parse(value).to_dict()["relations"]) == 1
+
+
+def test_complete_zero_feature_coverage_is_preserved_and_same_category_overlap_rejected():
+    value = document()
+    value.update(features=[], lane_segments=[], relations=[])
+    region = {
+        "token": "inspected",
+        "geometry": square(),
+        "categories": [{"category_id": "area", "state": "complete"}],
+    }
+    value["coverage"] = [region]
+    assert parse(value).to_dict()["coverage"][0]["categories"][0]["state"] == "complete"
+    value["coverage"].append({**copy.deepcopy(region), "token": "duplicate-region"})
+    with pytest.raises(ValueError, match="overlaps"):
+        parse(value)
+    value["coverage"][1]["categories"][0]["category_id"] = "boundary"
+    parse(value)
+
+
+def test_schema_geometry_rules_are_mandatory_complete_and_do_not_supply_defaults():
+    body = map_schema_body()
+    del body["task_views"][0]["geometry_rules"]
+    with pytest.raises(ValueError):
+        parse_label_schema_body(body)
+    body = map_schema_body()
+    body["task_views"][0]["geometry_rules"][0]["geometry_types"] = ["polygon", "point"]
+    with pytest.raises(ValueError):
+        parse_label_schema_body(body)
+    value = document()
+    value["features"][0]["category_id"] = "area"
+    with pytest.raises(ValueError, match="does not permit"):
+        parse(value)
+
+
+def test_component_retain_replace_and_clear_are_distinct_and_explicit():
+    for operation in ("retain", "clear"):
+        value = {"operation": operation, "base_revision": None, "document": None}
+        assert parse_vector_map_change(value, map_schema(), clip_id="clip-a") == value
+    value = {"operation": "replace", "base_revision": None, "document": document()}
+    assert (
+        parse_vector_map_change(value, map_schema(), clip_id="clip-a")["document"]
+        == document()
+    )
+    with pytest.raises(ValueError):
+        parse_vector_map_change({"document": None}, map_schema(), clip_id="clip-a")

x4d_devkit-0.44.0rc1/tests/test_vector_map_geometry.py

@@ -0,0 +1,76 @@
+import pytest
+
+from x4d_devkit.vector_map_geometry import (
+    curve_sample,
+    polygon_interiors_overlap,
+    polygon_rings,
+    polyline_length,
+    validate_geometry,
+)
+
+
+def square(x=0, y=0, size=4):
+    return {
+        "type": "polygon",
+        "outer": [
+            [x, y, 2],
+            [x + size, y, 3],
+            [x + size, y + size, 4],
+            [x, y + size, 5],
+        ],
+        "holes": [],
+    }
+
+
+def test_measured_xyz_arc_length_and_interpolation_preserve_height():
+    geometry = {"type": "polyline", "coordinates": [[0, 0, 0], [0, 0, 3], [4, 0, 3]]}
+    assert polyline_length(geometry) == 7
+    assert curve_sample(geometry, 5) == [2, 0, 3]
+
+
+def test_polygon_holes_and_height_are_preserved_without_normalization():
+    geometry = square()
+    geometry["holes"] = [[[1, 1, 7], [1, 2, 8], [2, 2, 9], [2, 1, 10]]]
+    assert validate_geometry(geometry) == "polygon"
+    assert len(polygon_rings(geometry)) == 2
+    assert geometry["holes"][0][3][2] == 10
+
+
+@pytest.mark.parametrize(
+    "outer",
+    [
+        [[0, 0, 0], [0, 4, 0], [4, 4, 0], [4, 0, 0]],
+        [[0, 0, 0], [4, 4, 0], [0, 4, 0], [4, 0, 0]],
+        [[0, 0, 0], [4, 0, 0], [4, 4, 0], [0, 4, 0], [0, 0, 1]],
+    ],
+)
+def test_wrong_direction_crossings_and_duplicate_xy_are_rejected(outer):
+    with pytest.raises(ValueError):
+        polygon_rings({"type": "polygon", "outer": outer, "holes": []})
+
+
+def test_touching_or_external_holes_are_rejected():
+    geometry = square()
+    geometry["holes"] = [[[0, 1, 0], [0, 2, 0], [1, 2, 0], [1, 1, 0]]]
+    with pytest.raises(ValueError, match="strictly inside"):
+        polygon_rings(geometry)
+
+
+def test_coverage_interior_overlap_includes_identical_regions_but_not_touching():
+    assert polygon_interiors_overlap(square(), square())
+    assert polygon_interiors_overlap(square(), square(3, 1))
+    assert not polygon_interiors_overlap(square(), square(4, 0))
+    assert not polygon_interiors_overlap(square(), square(5, 0))
+
+
+def test_region_inside_another_regions_hole_is_not_overlapping():
+    geometry = square(size=10)
+    geometry["holes"] = [[[1, 1, 0], [1, 8, 0], [8, 8, 0], [8, 1, 0]]]
+    assert not polygon_interiors_overlap(geometry, square(2, 2, 2))
+    assert polygon_interiors_overlap(geometry, square(0, 0, 2))
+
+
+@pytest.mark.parametrize("coordinates", [[0, True, 1], [0, 1, float("nan")], [0, 1]])
+def test_points_reject_non_coordinates_without_coercion(coordinates):
+    with pytest.raises(ValueError, match="measured XYZ"):
+        validate_geometry({"type": "point", "coordinates": coordinates})

x4d_devkit-0.44.0rc1/tests/test_vector_map_session.py

@@ -0,0 +1,147 @@
+import copy
+import json
+from types import SimpleNamespace
+
+import pytest
+
+from tests.current_clip_fixtures import current_work_session_payload
+from tests.vector_map_fixtures import document, map_schema_body
+from tests.schema_contract_fixtures import schema_body
+from x4d_devkit import (
+    ClipLabelSchemaSnapshot,
+    ClipLoader,
+    materialize_work_session_clip,
+    parse_clip_work_session,
+    parse_vector_map,
+    validate_clip,
+)
+from x4d_devkit.client.clip_work_sessions import ClipWorkSessionsAPI
+from x4d_devkit.current_state import identity_from_work_session, diff_clip_identity
+from x4d_devkit.label_schema import LabelSchemaBody, LabelSchemaRecord
+
+
+def session():
+    value = current_work_session_payload()
+    body = schema_body()
+    addition = map_schema_body()
+    body["classes"].extend(addition["classes"])
+    body["task_views"].extend(addition["task_views"])
+    schema = ClipLabelSchemaSnapshot.from_record(
+        LabelSchemaRecord(
+            status="active",
+            fingerprint=LabelSchemaBody.from_dict(body).fingerprint,
+            body=body,
+        )
+    )
+    value["label_schema"] = schema.to_dict()
+    value["vector_map"] = document()
+    value["vector_map"]["provenance"]["label_schema_fingerprint"] = schema.fingerprint
+    value["vector_map_revision"] = parse_vector_map(
+        value["vector_map"], schema, clip_id=value["clip_id"]
+    ).revision
+    return value
+
+
+def test_work_session_loader_preserves_native_map_and_rejects_mismatched_revision():
+    value = session()
+    ws = parse_clip_work_session(value)
+    assert ws.to_dict()["vector_map"] == value["vector_map"]
+    assert (
+        ClipLoader.from_work_session(ws).vector_map.revision == ws.vector_map_revision
+    )
+    value["vector_map_revision"] = "sha256:" + "0" * 64
+    with pytest.raises(ValueError, match="does not match"):
+        parse_clip_work_session(value)
+
+
+def test_absent_component_and_previous_wire_version_fail_closed():
+    for mutation in ("missing", "revision", "version"):
+        value = current_work_session_payload()
+        if mutation == "missing":
+            del value["vector_map"]
+        elif mutation == "revision":
+            value["vector_map_revision"] = "sha256:" + "0" * 64
+        else:
+            value["contract_version"] = "x4d-clip-work-session-v9"
+        with pytest.raises(ValueError):
+            parse_clip_work_session(value)
+
+
+def test_map_only_refresh_and_clear_perform_zero_asset_requests(tmp_path):
+    import httpx
+
+    value = session()
+
+    def download(request):
+        return httpx.Response(200, content=bytes(96))
+
+    with httpx.Client(transport=httpx.MockTransport(download)) as client:
+        result = materialize_work_session_clip(
+            value, output_dir=tmp_path, api_url="http://fixture", client=SimpleNamespace(_http=client)
+        )
+    assert not result["errors"], result
+    initial = identity_from_work_session(value)
+    value["vector_map"]["features"][0]["attributes"] = {}
+    value["vector_map"]["features"][0]["geometry"]["coordinates"][0][2] += 0.1
+    value["vector_map_revision"] = parse_vector_map(
+        value["vector_map"],
+        parse_clip_work_session(session()).label_schema,
+        clip_id=value["clip_id"],
+    ).revision
+    assert diff_clip_identity(initial, identity_from_work_session(value)).changed == (
+        "vector_map_changed",
+    )
+
+    class NoMedia:
+        def get(self, *args, **kwargs):
+            raise AssertionError("map refresh requested media")
+
+    for clear in (False, True):
+        if clear:
+            value.update(vector_map=None, vector_map_revision=None)
+        result = materialize_work_session_clip(
+            value, output_dir=tmp_path, client=NoMedia(), components={"vector_map"}
+        )
+        assert not result["errors"], result
+        assert result["downloaded_assets"] == []
+        loader = ClipLoader(tmp_path)
+        assert (loader.vector_map is None) == clear
+        assert validate_clip(tmp_path).ok
+    assert not (tmp_path / "vector_map.json").exists()
+    assert (
+        json.loads((tmp_path / ".cache_identity.json").read_text())[
+            "vector_map_revision"
+        ]
+        is None
+    )
+
+
+def test_submit_requires_explicit_component_operation_and_pins_map_base():
+    ws = parse_clip_work_session(session())
+
+    class Client:
+        calls = []
+
+        def post(self, path, json):
+            self.calls.append(json)
+            return {"ok": True}
+
+    client = Client()
+    api = ClipWorkSessionsAPI(client)
+    with pytest.raises(TypeError):
+        api.submit_annotations(manifest=ws, annotations=ws.annotations)
+    change = {
+        "operation": "retain",
+        "base_revision": ws.vector_map_revision,
+        "document": None,
+    }
+    api.submit_annotations(
+        manifest=ws, annotations=ws.annotations, vector_map_change=change
+    )
+    assert client.calls[-1]["vector_map_change"] == change
+    invalid = copy.deepcopy(change)
+    invalid["base_revision"] = None
+    with pytest.raises(ValueError, match="base revision"):
+        api.submit_annotations(
+            manifest=ws, annotations=ws.annotations, vector_map_change=invalid
+        )

{x4d_devkit-0.43.0rc4 → x4d_devkit-0.44.0rc1}/tests/test_work_session.py

@@ -45,6 +45,8 @@ def _manifest() -> dict:
         "calibration_revision": "sha256:calib",
         "pose_revision": "sha256:pose",
         "semantic_scene_revision": None,
+        "vector_map_revision": None,
+        "vector_map": None,
         "business_metadata_revision": "sha256:business-metadata",
         "label_schema": clip_schema_snapshot(),
         "meta": {
@@ -554,7 +556,7 @@ def test_adopt_work_session_cache_only_replaces_current_identity_markers(
     assert adopted["verified_source_bytes"] > 0
     assert json.loads((tmp_path / ".cache_identity.json").read_text())[
         "schema_version"
-    ] == "x4d-cache-identity-v1"
+    ] == "x4d-cache-identity-v2"
     assert json.loads((tmp_path / ".x4d_identity.json").read_text())[
         "samples_revision"
     ] == source["samples_revision"]
@@ -600,6 +602,7 @@ def test_adopt_clip_identity_cache_accepts_only_current_portable_identity(
             {
                 **current_identity,
                 "semantic_scene_revision": "sha256:" + "f" * 64,
+                "vector_map_revision": None,
             },
             output_dir=tmp_path,
             materialization_policy="full",
@@ -926,6 +929,7 @@ def test_client_open_and_submit_use_manifest_conditional_identity():
     api = ClipWorkSessionsAPI(client)
     manifest = api.open(7, "clip-a")
     result = api.submit_annotations(
+        vector_map_change={"operation": "retain", "base_revision": None, "document": None},
         manifest=manifest,
         annotations=_manifest()["annotations"],
     )
@@ -948,6 +952,7 @@ def test_client_submit_requires_explicit_strict_annotations():
 
     with pytest.raises(TypeError, match="annotations must be a list"):
         api.submit_annotations(
+            vector_map_change={"operation": "retain", "base_revision": None, "document": None},
             manifest=manifest,
             annotations=None,
         )
@@ -965,6 +970,7 @@ def test_client_submit_preserves_explicit_empty_annotations():
     client = Client()
     api = ClipWorkSessionsAPI(client)
     api.submit_annotations(
+        vector_map_change={"operation": "retain", "base_revision": None, "document": None},
         manifest=parse_clip_work_session(_manifest()),
         annotations=[],
     )

{x4d_devkit-0.43.0rc4 → x4d_devkit-0.44.0rc1}/x4d_devkit/__init__.py

@@ -80,6 +80,13 @@ from x4d_devkit.semantic_scene_authoring import (
     parse_semantic_scene_authoring_work_session,
     validate_semantic_scene_authoring_semantic_upload,
 )
+from x4d_devkit.vector_map import (
+    VECTOR_MAP_CONTRACT_VERSION,
+    VectorMapDocument,
+    parse_vector_map,
+    parse_vector_map_change,
+    vector_map_geometry_rules,
+)
 from x4d_devkit.time_contract import TimeNs, canonical_epoch_ns, parse_time_ns
 from x4d_devkit.materialize import (
     adopt_clip_identity_cache,
@@ -103,6 +110,11 @@ from x4d_devkit.work_session import (
 )
 
 __all__ = [
+    "VECTOR_MAP_CONTRACT_VERSION",
+    "VectorMapDocument",
+    "parse_vector_map",
+    "parse_vector_map_change",
+    "vector_map_geometry_rules",
     "CLEAN_BASEMAP_CONTRACT_VERSION",
     "CleanBasemapManifest",
     "parse_clean_basemap_manifest",

{x4d_devkit-0.43.0rc4 → x4d_devkit-0.44.0rc1}/x4d_devkit/client/clip_work_sessions.py

@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING, Any
 import httpx
 
 from x4d_devkit.work_session import ClipWorkSessionManifest, parse_clip_work_session
+from x4d_devkit.vector_map import parse_vector_map_change
 
 if TYPE_CHECKING:
     from x4d_devkit.client.client import X4DClient
@@ -105,6 +106,7 @@ class ClipWorkSessionsAPI:
         base_annotation_revision: str | None = None,
         base_label_schema_fingerprint: str | None = None,
         annotations: list[dict[str, Any]],
+        vector_map_change: dict[str, Any],
     ) -> dict[str, Any]:
         """Conditionally submit one complete clip annotation state.
 
@@ -146,6 +148,15 @@ class ClipWorkSessionsAPI:
             raise ValueError(f"missing required work-session submit fields: {', '.join(missing)}")
         if type(annotations) is not list:
             raise TypeError("annotations must be a list")
+        if ws is None:
+            # Without a schema snapshot only retain/clear can be validated locally.
+            if not isinstance(vector_map_change, dict) or vector_map_change.get("operation") == "replace":
+                raise ValueError("map replacement requires the current complete manifest")
+        map_change = parse_vector_map_change(
+            vector_map_change, ws.label_schema if ws else None, clip_id=clip_id
+        )
+        if ws is not None and map_change["base_revision"] != ws.vector_map_revision:
+            raise ValueError("map change base revision differs from its work session")
         try:
             return self._client.post(
                 "/clip-work-sessions/submit-annotations",
@@ -156,6 +167,7 @@ class ClipWorkSessionsAPI:
                     "base_annotation_revision": base_annotation_revision,
                     "base_label_schema_fingerprint": base_label_schema_fingerprint,
                     "annotations": annotations,
+                    "vector_map_change": map_change,
                 },
             )
         except httpx.HTTPStatusError as exc:

{x4d_devkit-0.43.0rc4 → x4d_devkit-0.44.0rc1}/x4d_devkit/core/loader.py

@@ -120,6 +120,8 @@ def _tables_from_work_session(manifest: ClipWorkSessionManifest) -> dict[str, An
         "annotation.json": annotation_document.to_dict(),
         "label_schema.json": manifest.label_schema.to_dict(),
     }
+    if manifest.vector_map is not None:
+        tables["vector_map.json"] = manifest.vector_map
     return tables
 
 
@@ -285,6 +287,17 @@ class ClipLoader:
             _api_url=api_url,
         )
 
+    @property
+    def vector_map(self) -> Any:
+        """Return the immutable native map, or None when explicitly absent."""
+        if "vector_map.json" not in self._tables:
+            return None
+        from x4d_devkit.vector_map import parse_vector_map
+
+        return parse_vector_map(
+            self._tables["vector_map.json"], self._label_schema, clip_id=self.meta.clip_id
+        )
+
     def _read_json(self, name: str) -> Any:
         return self._tables[name]