fix(perception): reconstruct rolling occupancy from K1 increments

src/k1link/perception/contracts.py

@@ -56,6 +56,7 @@ class EvidenceCurrentness(StrEnum):
 
 class TemporalState(StrEnum):
     CURRENT = "current"
+    RETAINED = "retained"
     HELD = "held"
     EXPIRED = "expired"
 
@@ -617,6 +618,15 @@ class TemporalObstacle:
         if self.state is TemporalState.CURRENT:
             if self.age_ns > self.ttl_ns or not self.cells:
                 raise PerceptionContractError("current temporal occupancy requires bounded cells")
+        elif self.state is TemporalState.RETAINED:
+            if not 0 < self.age_ns <= self.ttl_ns or not self.cells:
+                raise PerceptionContractError(
+                    "retained rolling-map occupancy must remain within its bound"
+                )
+            if self.motion is not MotionState.UNKNOWN:
+                raise PerceptionContractError(
+                    "retained rolling-map occupancy cannot claim object motion"
+                )
         elif self.state is TemporalState.HELD:
             if not 0 < self.age_ns <= self.ttl_ns or not self.cells:
                 raise PerceptionContractError("held temporal state must remain within TTL")
@@ -755,10 +765,20 @@ class LocalObstacleMap:
         _nonnegative_integer(self.output_age_ns, "map output age")
         if self.free_space_claimed:
             raise PerceptionContractError("Milestone 4 cannot publish implicit free space")
-        if any(item.state is not TemporalState.CURRENT for item in self.occupied):
-            raise PerceptionContractError("occupied map entries must be current")
-        if any(item.state is TemporalState.CURRENT for item in self.unknown):
-            raise PerceptionContractError("held or expired map entries must remain unknown")
+        if any(
+            item.state not in {TemporalState.CURRENT, TemporalState.RETAINED}
+            for item in self.occupied
+        ):
+            raise PerceptionContractError(
+                "occupied map entries must be current hits or bounded rolling-map retention"
+            )
+        if any(
+            item.state in {TemporalState.CURRENT, TemporalState.RETAINED}
+            for item in self.unknown
+        ):
+            raise PerceptionContractError(
+                "held or expired temporal entries must remain unknown"
+            )
         component_ids = [item.component_id for item in (*self.occupied, *self.unknown)]
         if len(set(component_ids)) != len(component_ids):
             raise PerceptionContractError("map component identities must be unique")