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

1"""ICacheable Protocol definition."""

2

3 from typing import BinaryIO, Protocol, runtime_checkable

4

5

6@runtime_checkable

7 class 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 ...