x4d-devkit 0.43.0rc2__tar.gz → 0.43.0rc4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.43.0rc2
+Version: 0.43.0rc4
 Summary: Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation
 Author: windzu
 License-Expression: Apache-2.0

{x4d_devkit-0.43.0rc2 → x4d_devkit-0.43.0rc4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.43.0rc2"
+version = "0.43.0rc4"
 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.0rc2 → x4d_devkit-0.43.0rc4}/tests/test_clean_basemap.py

@@ -10,6 +10,7 @@ from x4d_devkit.clean_basemap import (
     CLEAN_BASEMAP_CONTRACT_VERSION,
     CLEAN_BASEMAP_INPUT_FIELDS,
     DECISION_CODES,
+    KEEP_CODES,
     KEEP_GROUND,
     MAPPING_DTYPE,
     REMOVE_MODEL_DYNAMIC,
@@ -24,6 +25,7 @@ from x4d_devkit.clean_basemap import (
     validate_clean_basemap_annotation,
     validate_clean_basemap_native_binding,
     validate_clean_basemap_resource,
+    compute_clean_basemap_preannotation_revision,
 )
 from x4d_devkit.semantic_scene_contract import (
     compute_annotation_dependency_revisions,
@@ -96,6 +98,9 @@ def fixture():
         },
     }
     inputs = {key: "sha256:" + "b" * 64 for key in CLEAN_BASEMAP_INPUT_FIELDS}
+    inputs["preannotation_revision"] = compute_clean_basemap_preannotation_revision(
+        None
+    )
     dependencies = compute_annotation_dependency_revisions(native["annotation"])
     for key in inputs:
         if key in dependencies:
@@ -109,6 +114,7 @@ def fixture():
             inputs, profile
         ),
         "input_identity": inputs,
+        "preannotation_evidence": None,
         "profile": profile,
         "point_count": 4,
         "bounds": [xyz.min(0).tolist(), xyz.max(0).tolist()],
@@ -308,6 +314,54 @@ def test_previous_contract_and_decision_bytes_are_rejected():
         )
 
 
+@pytest.mark.parametrize("family", ["decisions", "mapping"])
+def test_every_byte_in_the_last_record_obeys_its_exact_decision_domain(family):
+    count = 4096
+    anchor = "sha256:" + "a" * 64
+    if family == "decisions":
+        carrier = encode_clean_basemap_decisions(
+            asset_sha256=anchor, decisions=np.full(count, KEEP_GROUND)
+        )
+        domain = DECISION_CODES
+        decode = decode_clean_basemap_decisions
+        arguments = dict(asset_sha256=anchor, point_count=count)
+        byte_offset = -1
+    else:
+        carrier = encode_clean_basemap_mapping(
+            geometry_raw_sha256=anchor,
+            sweep_indices=np.zeros(count, dtype=np.uint32),
+            raw_point_ordinals=np.arange(count),
+            timestamps_ns=np.full(count, 100),
+            owner_source_indices=np.zeros(count, dtype=np.uint32),
+            owner_point_ordinals=np.arange(count),
+            decisions=np.full(count, KEEP_GROUND),
+        )
+        domain = KEEP_CODES
+        decode = decode_clean_basemap_mapping
+        arguments = dict(geometry_raw_sha256=anchor, point_count=count)
+        byte_offset = -MAPPING_DTYPE.itemsize + MAPPING_DTYPE.fields["decision"][1]
+    raw = bytearray(zstandard.ZstdDecompressor().decompress(carrier.payload))
+    for code in range(256):
+        raw[byte_offset] = code
+        payload = zstandard.ZstdCompressor().compress(raw)
+        descriptor = carrier.descriptor(family)
+        descriptor.update(
+            path=f"generated/reconstruction/clean_basemap/{family}/{sha256_bytes(payload)[7:]}.zst",
+            sha256=sha256_bytes(payload),
+            raw_sha256=sha256_bytes(bytes(raw)),
+            size_bytes=len(payload),
+        )
+        if code in domain:
+            values = decode(payload, descriptor=descriptor, **arguments)
+            decisions = values if family == "decisions" else values["decision"]
+            assert decisions[-1] == code
+            assert np.all(decisions[:-1] == KEEP_GROUND)
+        else:
+            message = "decision" if family == "decisions" else "mapping records"
+            with pytest.raises(ValueError, match=message):
+                decode(payload, descriptor=descriptor, **arguments)
+
+
 def test_pose_coverage_rejections_are_accounted_and_cannot_be_mapped():
     manifest, assets, _ = fixture()
     sweep = manifest["sweep_sources"][0]

x4d_devkit-0.43.0rc4/tests/test_clean_basemap_preannotation.py

@@ -0,0 +1,96 @@
+import copy
+
+import pytest
+
+from tests.test_clean_basemap import fixture
+from x4d_devkit.clean_basemap import (
+    CLEAN_BASEMAP_PREANNOTATION_CONTRACT_VERSION,
+    clean_basemap_preannotation_reference,
+    compute_clean_basemap_dependency_identity,
+    compute_clean_basemap_preannotation_revision,
+    compute_clean_basemap_revision,
+    parse_clean_basemap_manifest,
+    validate_clean_basemap_preannotation_evidence,
+)
+
+
+def evidence_fixture():
+    manifest, _, native = fixture()
+    evidence = {
+        "contract_version": CLEAN_BASEMAP_PREANNOTATION_CONTRACT_VERSION,
+        "clip_id": manifest["clip_id"],
+        "candidate_id": "sha256:" + "c" * 64,
+        "profile_id": "detector-profile-1",
+        "pipeline_identity": "sha256:" + "d" * 64,
+        "checkpoint_identity": "sha256:" + "e" * 64,
+        "source_identity": {
+            key: manifest["input_identity"][key]
+            for key in (
+                "samples_revision",
+                "sweeps_revision",
+                "calibration_revision",
+                "pose_revision",
+            )
+        },
+        "annotation": native["annotation"],
+    }
+    manifest["preannotation_evidence"] = clean_basemap_preannotation_reference(evidence)
+    manifest["input_identity"]["preannotation_revision"] = (
+        compute_clean_basemap_preannotation_revision(evidence)
+    )
+    manifest["dependency_identity"] = compute_clean_basemap_dependency_identity(
+        manifest["input_identity"], manifest["profile"]
+    )
+    manifest["basemap_revision"] = compute_clean_basemap_revision(manifest)
+    return manifest, evidence
+
+
+def test_evidence_is_bound_separately_and_does_not_add_native_instances():
+    manifest, evidence = evidence_fixture()
+    before = copy.deepcopy(manifest["instance_sources"])
+    parsed = parse_clean_basemap_manifest(manifest)
+    assert (
+        validate_clean_basemap_preannotation_evidence(
+            evidence, clip_id=parsed.clip_id, input_identity=manifest["input_identity"]
+        )
+        == evidence
+    )
+    assert parsed.to_dict()["instance_sources"] == before
+    assert "annotation" not in parsed.to_dict()["preannotation_evidence"]
+
+
+@pytest.mark.parametrize(
+    "field",
+    ["samples_revision", "sweeps_revision", "calibration_revision", "pose_revision"],
+)
+def test_evidence_from_different_geometry_cannot_bind(field):
+    manifest, evidence = evidence_fixture()
+    evidence["source_identity"][field] = "sha256:" + "f" * 64
+    with pytest.raises(ValueError, match="source differs"):
+        validate_clean_basemap_preannotation_evidence(
+            evidence,
+            clip_id=manifest["clip_id"],
+            input_identity=manifest["input_identity"],
+        )
+
+
+def test_different_candidate_or_absent_evidence_requires_new_identity():
+    manifest, evidence = evidence_fixture()
+    evidence["candidate_id"] = "sha256:" + "f" * 64
+    with pytest.raises(ValueError, match="revision differs"):
+        validate_clean_basemap_preannotation_evidence(
+            evidence,
+            clip_id=manifest["clip_id"],
+            input_identity=manifest["input_identity"],
+        )
+    with pytest.raises(ValueError, match="revision differs"):
+        validate_clean_basemap_preannotation_evidence(
+            None, clip_id=manifest["clip_id"], input_identity=manifest["input_identity"]
+        )
+
+
+def test_historical_v2_is_rejected_even_with_current_fields():
+    manifest, _ = evidence_fixture()
+    manifest["contract_version"] = "x4d-clean-static-basemap-v2"
+    with pytest.raises(ValueError, match="current contract"):
+        parse_clean_basemap_manifest(manifest)

{x4d_devkit-0.43.0rc2 → x4d_devkit-0.43.0rc4}/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.0rc2"
+    assert x4d_devkit.__version__ == "0.43.0rc4"
 
 
 def test_loader_exposes_and_enforces_only_current_schema(tmp_path):

{x4d_devkit-0.43.0rc2 → x4d_devkit-0.43.0rc4}/x4d_devkit/clean_basemap.py

@@ -36,7 +36,11 @@ from x4d_devkit.semantic_scene_contract import (
 )
 from x4d_devkit.time_contract import parse_time_ns
 
-CLEAN_BASEMAP_CONTRACT_VERSION = "x4d-clean-static-basemap-v2"
+CLEAN_BASEMAP_CONTRACT_VERSION = "x4d-clean-static-basemap-v3"
+CLEAN_BASEMAP_PREANNOTATION_CONTRACT_VERSION = "x4d-clean-basemap-preannotation-v1"
+_GEOMETRY_INPUT_FIELDS = frozenset(
+    {"samples_revision", "sweeps_revision", "calibration_revision", "pose_revision"}
+)
 CLEAN_BASEMAP_OPERATION = "reconstruction.prepare_clean_static_basemap"
 CLEAN_BASEMAP_MAPPING_FORMAT = "x4d-clean-static-basemap-mapping-v1"
 CLEAN_BASEMAP_DECISION_FORMAT = "x4d-clean-static-basemap-decisions-v2"
@@ -49,6 +53,7 @@ CLEAN_BASEMAP_INPUT_FIELDS = frozenset(
         "scene_ownership_revision",
         "instance_shape_input_revision",
         "image_input_revision",
+        "preannotation_revision",
     }
 )
 KEEP_STATIC = 0
@@ -183,6 +188,117 @@ def compute_clean_basemap_revision(value: Mapping[str, Any]) -> str:
     return canonical_json_sha256(data)
 
 
+def parse_clean_basemap_preannotation_evidence(value: Any) -> dict | None:
+    """Validate supplemental hypotheses without granting native ownership."""
+    if value is None:
+        return None
+    data = _thaw(value)
+    _object(
+        data,
+        {
+            "contract_version",
+            "clip_id",
+            "candidate_id",
+            "profile_id",
+            "pipeline_identity",
+            "checkpoint_identity",
+            "source_identity",
+            "annotation",
+        },
+        "preannotation_evidence",
+    )
+    ensure_i_json(data, path="preannotation_evidence")
+    if data["contract_version"] != CLEAN_BASEMAP_PREANNOTATION_CONTRACT_VERSION:
+        raise ValueError("preannotation evidence requires the current contract")
+    parse_portable_token(data["clip_id"], path="preannotation_evidence.clip_id")
+    parse_portable_token(data["profile_id"], path="preannotation_evidence.profile_id")
+    for key in ("candidate_id", "pipeline_identity", "checkpoint_identity"):
+        _hash(data[key], f"preannotation_evidence.{key}")
+    _object(
+        data["source_identity"], _GEOMETRY_INPUT_FIELDS, "preannotation source_identity"
+    )
+    for key, identity in data["source_identity"].items():
+        _hash(identity, f"preannotation source_identity.{key}")
+    annotation = parse_clip_annotations(data["annotation"])
+    if annotation.clip_id != data["clip_id"]:
+        raise ValueError("preannotation evidence annotation belongs to another Clip")
+    data["annotation"] = annotation.to_dict()
+    return data
+
+
+def clean_basemap_preannotation_reference(value: Any) -> dict | None:
+    data = parse_clean_basemap_preannotation_evidence(value)
+    if data is None:
+        return None
+    annotation = data.pop("annotation")
+    return {**data, "annotation_revision": annotation["annotation_revision"]}
+
+
+def compute_clean_basemap_preannotation_revision(value: Any) -> str:
+    return canonical_json_sha256(
+        {"evidence": clean_basemap_preannotation_reference(value)}
+    )
+
+
+def _validate_preannotation_reference(reference, *, clip_id, input_identity):
+    if reference is not None:
+        _object(
+            reference,
+            {
+                "contract_version",
+                "clip_id",
+                "candidate_id",
+                "profile_id",
+                "pipeline_identity",
+                "checkpoint_identity",
+                "source_identity",
+                "annotation_revision",
+            },
+            "preannotation_evidence",
+        )
+        if (
+            reference["contract_version"]
+            != CLEAN_BASEMAP_PREANNOTATION_CONTRACT_VERSION
+            or reference["clip_id"] != clip_id
+        ):
+            raise ValueError("preannotation evidence contract or Clip differs")
+        parse_portable_token(
+            reference["profile_id"], path="preannotation_evidence.profile_id"
+        )
+        for key in (
+            "candidate_id",
+            "pipeline_identity",
+            "checkpoint_identity",
+            "annotation_revision",
+        ):
+            _hash(reference[key], f"preannotation_evidence.{key}")
+        _object(
+            reference["source_identity"],
+            _GEOMETRY_INPUT_FIELDS,
+            "preannotation source_identity",
+        )
+        if reference["source_identity"] != {
+            key: input_identity[key] for key in _GEOMETRY_INPUT_FIELDS
+        }:
+            raise ValueError("preannotation evidence source differs from clean basemap")
+    if (
+        canonical_json_sha256({"evidence": reference})
+        != input_identity["preannotation_revision"]
+    ):
+        raise ValueError("preannotation evidence revision differs from clean basemap")
+
+
+def validate_clean_basemap_preannotation_evidence(value, *, clip_id, input_identity):
+    """Validate the full frozen evidence against its manifest dependency."""
+    data = parse_clean_basemap_preannotation_evidence(value)
+    _validate_preannotation_reference(
+        clean_basemap_preannotation_reference(data),
+        clip_id=clip_id,
+        input_identity=input_identity,
+    )
+    return data
+
+
 def compute_clean_basemap_dependency_identity(
     input_identity: Mapping[str, str], profile: Mapping[str, Any]
 ) -> str:
@@ -285,6 +401,7 @@ def parse_clean_basemap_manifest(
             "basemap_revision",
             "dependency_identity",
             "input_identity",
+            "preannotation_evidence",
             "profile",
             "point_count",
             "bounds",
@@ -303,6 +420,11 @@ def parse_clean_basemap_manifest(
     ):
         raise ValueError("clean basemap requires the current contract in clip_world")
     parse_portable_token(data["clip_id"], path="clean_basemap.clip_id")
+    _validate_preannotation_reference(
+        data["preannotation_evidence"],
+        clip_id=data["clip_id"],
+        input_identity=data["input_identity"],
+    )
     _hash(data["basemap_revision"], "basemap_revision")
     if data["dependency_identity"] != compute_clean_basemap_dependency_identity(
         data["input_identity"], data["profile"]
@@ -528,9 +650,8 @@ def encode_clean_basemap_mapping(
     }
     count = len(vectors["sweep_index"])
     _integer(count, 1, SEMANTIC_SCENE_MAX_SCENE_POINTS_PER_CHUNK, "point_count")
-    if (
-        any(len(vector) != count for vector in vectors.values())
-        or not set(int(v) for v in vectors["decision"]) <= KEEP_CODES
+    if any(len(vector) != count for vector in vectors.values()) or np.any(
+        ~np.isin(vectors["decision"], tuple(KEEP_CODES))
     ):
         raise ValueError(
             "mapping must have one retained decision and address per geometry point"
@@ -560,7 +681,7 @@ def decode_clean_basemap_mapping(
     )
     if (
         np.any(records["reserved"] != 0)
-        or not set(int(v) for v in records["decision"]) <= KEEP_CODES
+        or np.any(~np.isin(records["decision"], tuple(KEEP_CODES)))
         or np.any(records["timestamp_ns"] > _MAX_I64)
     ):
         raise ValueError(
@@ -574,7 +695,7 @@ def encode_clean_basemap_decisions(
 ) -> CleanBasemapPayload:
     values = _vector(decisions, 255, "decisions")
     _integer(len(values), 1, 1 << 24, "source_point_count")
-    if not set(int(v) for v in values) <= DECISION_CODES:
+    if np.any(~np.isin(values, tuple(DECISION_CODES))):
         raise ValueError("unknown clean basemap decision code")
     return _encode(_DECISION_MAGIC, asset_sha256, values.astype(np.uint8))
 
@@ -591,7 +712,7 @@ def decode_clean_basemap_decisions(
     values = _decode(
         payload, descriptor, _DECISION_MAGIC, asset_sha256, point_count, np.dtype("u1")
     )
-    if not set(int(v) for v in values) <= DECISION_CODES:
+    if np.any(~np.isin(values, tuple(DECISION_CODES))):
         raise ValueError("unknown clean basemap decision code")
     return values
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.43.0rc2
+Version: 0.43.0rc4
 Summary: Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation
 Author: windzu
 License-Expression: Apache-2.0

{x4d_devkit-0.43.0rc2 → x4d_devkit-0.43.0rc4}/x4d_devkit.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ tests/test_box.py
 tests/test_build_info.py
 tests/test_clean_basemap.py
 tests/test_clean_basemap_client.py
+tests/test_clean_basemap_preannotation.py
 tests/test_cli_auth.py
 tests/test_client_json_contract.py
 tests/test_client_projects.py