Coverage for src / invariant / protocol.py: 70.00%

1"""ICacheable Protocol definition.""" 

2 

3from typing import BinaryIO, Protocol, runtime_checkable 

4 

5 

6@runtime_checkable 

7class ICacheable(Protocol): 

8 """Protocol for all cacheable data types. 

9 

10 All data passed between Nodes must implement this protocol to ensure 

11 valid Manifest construction and artifact storage. 

12 """ 

13 

14 def get_stable_hash(self) -> str: 

15 """Returns a deterministic SHA-256 hash of the object's structural state. 

16 

17 This represents the 'Identity' of the data. The hash must be: 

18 - Deterministic: Same inputs always produce same hash 

19 - Stable: Hash doesn't change across serialization/deserialization 

20 - Collision-resistant: Different inputs should produce different hashes 

21 

22 Returns: 

23 A hexadecimal SHA-256 hash string (64 characters). 

24 """ 

25 ... 

26 

27 def to_stream(self, stream: BinaryIO) -> None: 

28 """Serializes the object to a binary stream for persistent storage. 

29 

30 Args: 

31 stream: A binary I/O stream to write the serialized data to. 

32 

33 The serialization format must be deterministic and allow for 

34 complete reconstruction via from_stream. 

35 """ 

36 ... 

37 

38 @classmethod 

39 def from_stream(cls, stream: BinaryIO) -> "ICacheable": 

40 """Hydrates the object from a binary stream. 

41 

42 Args: 

43 stream: A binary I/O stream to read the serialized data from. 

44 

45 Returns: 

46 An instance of the class with state restored from the stream. 

47 

48 This must be the inverse operation of to_stream. 

49 """ 

50 ...