@@ -553,24 +553,6 @@ reviews:
553553 - Protobuf-aligned with Hedera/Hiero
554554 - Gas/value safe
555555 - Deterministic and user-protective
556-
557- # GLOBAL REVIEW INSTRUCTIONS
558- python_review_instructions : &python_review_instructions |
559- **CRITICAL FOCUS - Protobuf Alignment**
560- When reviewing Python files, check for imports containing "hapi" in the format :
561- ` from hiero_sdk_python.hapi.<path> import <module>_pb2`
562-
563- For each such import found :
564- 1. Extract the path component after "hapi" (e.g., "services" from "hapi.services")
565- 2. Extract the module name before "_pb2" (e.g., "consensus_submit_message" from "consensus_submit_message_pb2")
566- 3. Construct the canonical schema URL :
567- https://github.com/hashgraph/hedera-protobufs/blob/main/<path>/<module>.proto
568-
569- Example :
570- For import : ` from hiero_sdk_python.hapi.services import consensus_submit_message_pb2`
571- Generate : https://github.com/hashgraph/hedera-protobufs/blob/main/services/consensus_submit_message.proto
572- Ensure all message fields and types align with the latest definitions in the referenced .proto file.
573- Flag any discrepancies in field names, types, or required/optional status.
574556
575557 # ============================================================
576558 # GLOBAL REVIEW INSTRUCTIONS (APPLY TO ALL FILES)
@@ -1099,8 +1081,113 @@ reviews:
10991081 - path : " src/hiero_sdk_python/contract/**"
11001082 instructions : *contract_review_instructions
11011083
1102- - path : " src/hiero_sdk_python/consensus/**/*.py"
1103- instructions : *python_review_instructions
1084+ - path : " src/hiero_sdk_python/**/*.py"
1085+ instructions : |
1086+ ## Protobuf Schema Alignment Review
1087+
1088+ # ## Step 1 — Detect protobuf imports
1089+
1090+ Scan the file for all imports matching this pattern :
1091+ ` from hiero_sdk_python.hapi.<path> import <module>_pb2`
1092+
1093+ For each import found, skip `_grpc` stubs (those end in `_pb2_grpc`) — only
1094+ process `_pb2` message modules.
1095+
1096+ # ## Step 2 — Construct the canonical schema URL
1097+
1098+ For each `_pb2` import :
1099+ 1. Extract the path segment after `hapi`
1100+ (e.g. `services` from `hiero_sdk_python.hapi.services`)
1101+ 2. Extract the module name before `_pb2`
1102+ (e.g. `transaction_record` from `transaction_record_pb2`)
1103+ 3. Build the canonical URL :
1104+ ` https://github.com/hashgraph/hedera-protobufs/blob/main/<path>/<module>.proto`
1105+
1106+ **Example:**
1107+ ` ` `
1108+ Import: from hiero_sdk_python.hapi.services import transaction_record_pb2
1109+ Schema: https://github.com/hashgraph/hedera-protobufs/blob/main/services/transaction_record.proto
1110+ ` ` `
1111+
1112+ # ## Step 3 — Compare the SDK class against the proto schema
1113+
1114+ For each SDK class that calls `_from_proto` or `_to_proto` using messages from
1115+ the detected proto module, verify the following :
1116+
1117+ # ### 3a. Field coverage
1118+ - Every non-deprecated proto field SHOULD have a corresponding SDK attribute.
1119+ - Flag any proto field that is present in the schema but missing from the SDK
1120+ class (either as a dataclass field or handled in `_from_proto`).
1121+ - Flag any SDK attribute that references a proto field name that does not exist
1122+ in the schema.
1123+
1124+ # ### 3b. Field name mapping
1125+ - Proto field names use `snake_case` (e.g. `ethereum_hash`) or `camelCase`
1126+ (e.g. `transactionHash`, `consensusTimestamp`). Verify that `_from_proto`
1127+ accesses the correct proto field name, not a renamed/misspelled version.
1128+ - Verify `_to_proto` sets the correct proto field name.
1129+
1130+ # ### 3c. Field type alignment
1131+ Check that each SDK field type correctly represents the proto type :
1132+
1133+ | Proto type | Expected SDK type |
1134+ |------------------------|----------------------------------------------|
1135+ | `string` | `str \| None` or `str` |
1136+ | `bytes` | `bytes \| None` or `bytes` |
1137+ | `bool` | `bool` |
1138+ | `int32`, `uint32` | `int` |
1139+ | `int64`, `uint64`, `sint64` | `int` |
1140+ | `MessageType` | corresponding SDK wrapper class or `None` |
1141+ | `repeated MessageType` | `list[SdkType]` |
1142+ | `repeated scalar` | `list[scalar]` |
1143+
1144+ # ### 3d. `oneof` field handling
1145+ - Identify all `oneof` blocks in the proto schema for the message.
1146+ - Verify that `_to_proto` does NOT set more than one field from the same
1147+ ` oneof` block simultaneously. If it does, a `ValueError` guard MUST be
1148+ present before setting those fields.
1149+ - Verify that `_from_proto` uses `proto.HasField(...)` (not attribute access)
1150+ to detect which branch of a `oneof` is populated.
1151+ - Common `oneof` groups to watch for in `TransactionRecord` :
1152+ - ` oneof body { contractCallResult, contractCreateResult }` (fields 7, 8)
1153+ - ` oneof entropy { prng_bytes, prng_number }` (fields 19, 20)
1154+
1155+ # ### 3e. Bytes field normalization
1156+ - Proto `bytes` fields default to `b""` (empty bytes) when unset, not `None`.
1157+ - If the SDK models the field as `bytes | None`, verify that `_from_proto`
1158+ uses `proto.<field> or None` to normalize empty bytes to `None`.
1159+ - Conversely, if `_to_proto` sets a bytes field, verify it guards against
1160+ setting `None` (which would cause a protobuf type error).
1161+
1162+ # ### 3f. `_from_proto` / `_to_proto` symmetry
1163+ - Every field parsed in `_from_proto` SHOULD also be serialized in `_to_proto`,
1164+ and vice versa, unless the field is intentionally read-only (e.g. server-set
1165+ fields that clients never send).
1166+ - Flag any asymmetry that is not accompanied by a code comment explaining why.
1167+
1168+ # ### 3g. Repeated field default values
1169+ - SDK attributes representing proto `repeated` fields MUST default to an empty
1170+ list (`field(default_factory=list)`), never `None`.
1171+ - Flag any `repeated` field that defaults to `None`.
1172+
1173+ # ### 3h. Type annotation consistency
1174+ - The codebase uses `X | None` union syntax (Python 3.10+). Flag any use of
1175+ ` Optional[X]` from `typing` in newly added or modified code, as it is
1176+ inconsistent with the established style.
1177+
1178+ # ## Step 4 — Report format
1179+
1180+ For each issue found, report :
1181+ - **File and line**: where the issue occurs
1182+ - **Proto field**: the canonical proto field name and number from the schema
1183+ - **Issue type**: one of — Missing field | Wrong field name | Wrong type |
1184+ oneof violation | Bytes not normalized | Asymmetric round-trip |
1185+ Wrong default | Style inconsistency
1186+ - **Description**: concise explanation of the discrepancy
1187+ - **Suggested fix**: the corrected code snippet
1188+
1189+ If no issues are found for a file, state :
1190+ ✅ All mapped proto fields align with the schema at `<URL>`.
11041191
11051192 - path : " src/hiero_sdk_python/consensus/**/*.py"
11061193 instructions : |
0 commit comments