1818
1919from __future__ import annotations
2020
21+ import base64
2122import contextlib
2223import hashlib
2324import logging
2425import math
2526import random
27+ import re
2628import uuid
2729from collections .abc import Callable , Iterable , Mapping , Sequence
2830from copy import copy
@@ -965,6 +967,96 @@ def to_server_command(
965967 }
966968
967969
970+ _MEMO_KEY_PATTERN = re .compile (r"^(?!-?[0-9]+$)[A-Za-z0-9_.:-]{1,64}$" )
971+ _MAX_MEMO_ENTRIES = 100
972+ _MAX_MEMO_VALUE_SIZE_BYTES = 10_240
973+ _MAX_MEMO_TOTAL_SIZE_BYTES = 65_536
974+
975+
976+ def _canonical_memo_value (value : Any ) -> Any :
977+ value = serializer .to_avro_payload_value (value )
978+ if isinstance (value , Mapping ):
979+ normalized : dict [str , Any ] = {}
980+ for key , nested in value .items ():
981+ if not isinstance (key , str ):
982+ raise ValueError ("workflow memo map keys must be strings" )
983+ normalized [key ] = _canonical_memo_value (nested )
984+ return {key : normalized [key ] for key in sorted (normalized )}
985+ if isinstance (value , list ):
986+ return [_canonical_memo_value (item ) for item in value ]
987+ serializer .encode (value , size_warning = None )
988+ return value
989+
990+
991+ def _memo_avro_bytes (value : Any ) -> bytes :
992+ return base64 .b64decode (serializer .encode (value , size_warning = None ), validate = True )
993+
994+
995+ def _memo_replay_identity (value : Mapping [str , Any ]) -> str :
996+ return serializer .encode (_canonical_memo_entries (value ), size_warning = None )
997+
998+
999+ def _canonical_memo_entries (entries : Mapping [str , Any ], * , require_entries : bool = True ) -> dict [str , Any ]:
1000+ if require_entries and not entries :
1001+ raise ValueError ("workflow memo updates require at least one entry" )
1002+ if len (entries ) > _MAX_MEMO_ENTRIES :
1003+ raise ValueError (f"workflow memo updates may contain at most { _MAX_MEMO_ENTRIES } entries" )
1004+
1005+ normalized : dict [str , Any ] = {}
1006+ for key , value in entries .items ():
1007+ if not isinstance (key , str ) or _MEMO_KEY_PATTERN .fullmatch (key ) is None :
1008+ raise ValueError ("workflow memo keys must match ^(?!-?[0-9]+$)[A-Za-z0-9_.:-]{1,64}$" )
1009+ canonical = _canonical_memo_value (value )
1010+ if len (_memo_avro_bytes (canonical )) > _MAX_MEMO_VALUE_SIZE_BYTES :
1011+ raise ValueError (
1012+ f"workflow memo value { key !r} exceeds the { _MAX_MEMO_VALUE_SIZE_BYTES } -byte limit"
1013+ )
1014+ normalized [key ] = canonical
1015+
1016+ normalized = {key : normalized [key ] for key in sorted (normalized )}
1017+ if len (_memo_avro_bytes (normalized )) > _MAX_MEMO_TOTAL_SIZE_BYTES :
1018+ raise ValueError (
1019+ f"workflow memo update exceeds the { _MAX_MEMO_TOTAL_SIZE_BYTES } -byte total limit"
1020+ )
1021+ return normalized
1022+
1023+
1024+ @dataclass
1025+ class UpsertMemo :
1026+ """Merge non-indexed workflow memo metadata through durable history.
1027+
1028+ ``None`` deletes a key. The SDK encodes the complete patch in the public
1029+ Avro payload envelope consumed by Server and Cloud runtimes.
1030+ """
1031+
1032+ entries : dict [str , Any ]
1033+
1034+ def __post_init__ (self ) -> None :
1035+ self .entries = _canonical_memo_entries (self .entries )
1036+
1037+ def to_server_command (
1038+ self ,
1039+ task_queue : str ,
1040+ * ,
1041+ payload_codec : str = serializer .AVRO_CODEC ,
1042+ size_warning : serializer .PayloadSizeWarningConfig | None = serializer .DEFAULT_PAYLOAD_SIZE_WARNING ,
1043+ warning_context : PayloadWarningContext = None ,
1044+ ) -> dict [str , Any ]:
1045+ return {
1046+ "type" : "upsert_memo" ,
1047+ "entries" : serializer .envelope (
1048+ self .entries ,
1049+ codec = payload_codec ,
1050+ size_warning = size_warning ,
1051+ warning_context = _payload_warning_context (
1052+ warning_context ,
1053+ kind = "workflow_memo_entries" ,
1054+ task_queue = task_queue ,
1055+ ),
1056+ ),
1057+ }
1058+
1059+
9681060@dataclass
9691061class WaitCondition :
9701062 """Command that yields execution until a workflow-defined predicate becomes true.
@@ -1026,7 +1118,7 @@ def _condition_predicate_fingerprint(predicate: Callable[[], bool]) -> str:
10261118Command = (
10271119 ScheduleActivity | StartTimer | CompleteWorkflow | FailWorkflow
10281120 | CompleteUpdate | FailUpdate | ContinueAsNew | RecordSideEffect | StartChildWorkflow
1029- | NexusServiceCall | RecordVersionMarker | UpsertSearchAttributes | WaitCondition
1121+ | NexusServiceCall | RecordVersionMarker | UpsertMemo | UpsertSearchAttributes | WaitCondition
10301122)
10311123
10321124
@@ -1705,6 +1797,10 @@ def deprecate_patch(self, change_id: str) -> RecordVersionMarker:
17051797 def upsert_search_attributes (self , attributes : dict [str , Any ]) -> UpsertSearchAttributes :
17061798 return UpsertSearchAttributes (attributes = dict (attributes ))
17071799
1800+ def upsert_memo (self , entries : Mapping [str , Any ]) -> UpsertMemo :
1801+ """Return a replayable memo merge command with structural validation."""
1802+ return UpsertMemo (entries = dict (entries ))
1803+
17081804 def continue_as_new (
17091805 self ,
17101806 * args : Any ,
@@ -2770,6 +2866,11 @@ def _recorded_step_details(payload: Mapping[str, Any]) -> dict[str, Any]:
27702866 value = payload .get (key )
27712867 if isinstance (value , str ) and value :
27722868 details [key ] = value
2869+ entries = payload .get ("entries" )
2870+ if isinstance (entries , Mapping ):
2871+ details ["entries_identity" ] = _memo_replay_identity (
2872+ _decode_memo_history_map (entries , require_entries = True )
2873+ )
27732874 raw_parallel_path = payload .get ("parallel_group_path" )
27742875 if (
27752876 isinstance (raw_parallel_path , list )
@@ -2793,6 +2894,20 @@ def _recorded_step_details(payload: Mapping[str, Any]) -> dict[str, Any]:
27932894 return details
27942895
27952896
2897+ def _decode_memo_history_map (
2898+ envelope : Mapping [str , Any ],
2899+ * ,
2900+ require_entries : bool ,
2901+ ) -> dict [str , Any ]:
2902+ """Decode the inline Avro map envelope persisted in MemoUpserted history."""
2903+ if set (envelope ) != {"codec" , "blob" }:
2904+ raise ValueError ("MemoUpserted history requires exactly the public {codec, blob} payload envelope" )
2905+ decoded = serializer .decode_envelope (dict (envelope ))
2906+ if not isinstance (decoded , Mapping ):
2907+ raise ValueError ("MemoUpserted Avro payload must decode to a string-keyed map" )
2908+ return _canonical_memo_entries (decoded , require_entries = require_entries )
2909+
2910+
27962911def _is_resolved_step_event (
27972912 event_type : str | None ,
27982913 payload : Mapping [str , Any ],
@@ -2808,6 +2923,7 @@ def _is_resolved_step_event(
28082923 "ChildRunTerminated" ,
28092924 "SideEffectRecorded" ,
28102925 "VersionMarkerRecorded" ,
2926+ "MemoUpserted" ,
28112927 "SearchAttributesUpserted" ,
28122928 ):
28132929 return True
@@ -2829,6 +2945,8 @@ def _command_history_shape(command: Any) -> str | None:
28292945 return "side effect"
28302946 if isinstance (command , RecordVersionMarker ):
28312947 return "version marker"
2948+ if isinstance (command , UpsertMemo ):
2949+ return "memo upsert"
28322950 if isinstance (command , UpsertSearchAttributes ):
28332951 return "search attributes upsert"
28342952 if isinstance (command , WaitCondition ):
@@ -2882,6 +3000,10 @@ def _recorded_detail_mismatch(command: Any, step: _RecordedStep) -> str | None:
28823000 f"Recorded version change_id { recorded !r} , but current workflow "
28833001 f"requested { command .change_id !r} ."
28843002 )
3003+ elif isinstance (command , UpsertMemo ):
3004+ recorded = step .details .get ("entries_identity" )
3005+ if isinstance (recorded , str ) and recorded != _memo_replay_identity (command .entries ):
3006+ return "Recorded memo entries differ from the current workflow memo update."
28853007 return None
28863008
28873009
@@ -3047,7 +3169,13 @@ def _replay_state(
30473169 continue
30483170 if event_type is not None :
30493171 event_types_by_sequence .setdefault (sequence , []).append (event_type )
3050- details_by_sequence .setdefault (sequence , {}).update (_recorded_step_details (payload ))
3172+ try :
3173+ recorded_details = _recorded_step_details (payload )
3174+ except (TypeError , ValueError ):
3175+ # The sequence-specific history parser below turns malformed memo
3176+ # envelopes into the public non-determinism diagnostic.
3177+ recorded_details = {}
3178+ details_by_sequence .setdefault (sequence , {}).update (recorded_details )
30513179 if event_type == "ConditionWaitOpened" :
30523180 wait_id = payload .get ("condition_wait_id" )
30533181 if isinstance (wait_id , str ) and wait_id :
@@ -3102,6 +3230,7 @@ def _state(commands: list[Command]) -> _ReplayState:
31023230 recorded_wait_steps : list [_RecordedStep ] = []
31033231 recorded_pending_steps : list [_RecordedStep ] = []
31043232 pending_sequences_added : set [int ] = set ()
3233+ memo_sequences_added : set [int ] = set ()
31053234 # External receivers normally apply by resolved-result cursor. Receivers
31063235 # observed while a condition wait is open are pinned to that wait so
31073236 # sequential signal-driven waits do not collapse to the same cursor.
@@ -3461,6 +3590,58 @@ def _receiver_condition_wait_bindings() -> dict[int, str | None]:
34613590 _append_pending_step ("child workflow" , ev )
34623591 elif etype == "VersionMarkerRecorded" :
34633592 _append_resolved_result (payload .get ("version" , 0 ), "version marker" , ev )
3593+ elif etype == "MemoUpserted" :
3594+ sequence = _workflow_sequence (payload )
3595+ if sequence is None :
3596+ raise NonDeterministicReplayError (
3597+ len (recorded_steps ) + 1 ,
3598+ "memo upsert with positive workflow sequence" ,
3599+ ["MemoUpserted" ],
3600+ detail = "MemoUpserted history must retain its replay sequence." ,
3601+ )
3602+ if sequence in memo_sequences_added :
3603+ raise NonDeterministicReplayError (
3604+ sequence ,
3605+ "one MemoUpserted event" ,
3606+ ["MemoUpserted" , "MemoUpserted" ],
3607+ detail = "A workflow sequence cannot record the same memo update twice." ,
3608+ )
3609+ entries = payload .get ("entries" )
3610+ if not isinstance (entries , Mapping ):
3611+ raise NonDeterministicReplayError (
3612+ sequence ,
3613+ "memo upsert with canonical entries" ,
3614+ ["MemoUpserted" ],
3615+ detail = "MemoUpserted history must retain the applied entries as replay identity." ,
3616+ )
3617+ try :
3618+ _decode_memo_history_map (entries , require_entries = True )
3619+ except (TypeError , ValueError ) as exc :
3620+ raise NonDeterministicReplayError (
3621+ sequence ,
3622+ "memo upsert with canonical Avro entries envelope" ,
3623+ ["MemoUpserted" ],
3624+ detail = f"MemoUpserted history has invalid entries: { exc } " ,
3625+ ) from exc
3626+ merged = payload .get ("merged" )
3627+ if not isinstance (merged , Mapping ):
3628+ raise NonDeterministicReplayError (
3629+ sequence ,
3630+ "memo upsert with merged projection" ,
3631+ ["MemoUpserted" ],
3632+ detail = "MemoUpserted history must retain the merged memo projection." ,
3633+ )
3634+ try :
3635+ _decode_memo_history_map (merged , require_entries = False )
3636+ except (TypeError , ValueError ) as exc :
3637+ raise NonDeterministicReplayError (
3638+ sequence ,
3639+ "memo upsert with merged Avro projection envelope" ,
3640+ ["MemoUpserted" ],
3641+ detail = f"MemoUpserted history has invalid merged projection: { exc } " ,
3642+ ) from exc
3643+ memo_sequences_added .add (sequence )
3644+ _append_resolved_result (None , "memo upsert" , ev )
34643645 elif etype == "SearchAttributesUpserted" :
34653646 _append_resolved_result (None , "search attributes upsert" , ev )
34663647 elif etype == "SignalReceived" :
@@ -3837,7 +4018,7 @@ def _terminal_state(value: Any, *, include_pending: bool) -> _ReplayState:
38374018 pending .append (cmd )
38384019 next_value = cmd .result
38394020 continue
3840- if isinstance (cmd , UpsertSearchAttributes ):
4021+ if isinstance (cmd , UpsertMemo | UpsertSearchAttributes ):
38414022 if result_cursor < len (resolved_results ):
38424023 _assert_next_step_matches (cmd )
38434024 next_value = resolved_results [result_cursor ]
0 commit comments