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

1"""ICacheable Protocol definition."""

2

3 from typing import BinaryIO, Protocol, runtime_checkable

4

5 try:

6 from typing import Self

7 except ImportError:

8 from typing_extensions import Self

9

10

11@runtime_checkable

12 class ICacheable(Protocol):

13 """Protocol for all cacheable data types.

14

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

16 valid Manifest construction and artifact storage.

17 """

18

19 def get_stable_hash(self) -> str:

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

21

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

23 - Deterministic: Same inputs always produce same hash

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

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

26

27 Returns:

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

29 """

30 ...

31

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

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

34

35 Args:

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

37

38 The serialization format must be deterministic and allow for

39 complete reconstruction via from_stream.

40 """

41 ...

42

43 @classmethod

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

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

46

47 Args:

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

49

50 Returns:

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

52

53 This must be the inverse operation of to_stream.

54 """

55 ...

56

57

58@runtime_checkable

59 class IJsonRepresentable(Protocol):

60 """Optional: ICacheable types can implement this for human-readable JSON in graph serialization."""

61

62 def to_json_value(self) -> dict:

63 """Return a JSON-serializable dict representation of this object."""

64 ...

65

66 @classmethod

67 def from_json_value(cls, obj: dict) -> Self:

68 """Reconstruct an instance from a JSON dict."""

69 ...