i.UdZddlmZddlZddlmZddlmZddlmZm Z m Z hdZ de d <Gd d e Zdd Zdd ZddZddZddZddZddZGddZeZedGddZy)u core/coherence/state_delta.py StateDelta — RFC 6902 JSON Patch proposal for multi-agent coherence. This module provides: - VALID_OPS: the 6 RFC 6902 operation names - PatchConflictError: raised when an "op: test" assertion fails - validate_patch(patch): True/False validation of RFC 6902 structure - apply_patch(state, patch): apply a patch list to a state dict, returning a NEW dict - StateDelta: frozen dataclass representing a proposed state change No external libraries (jsonpatch, etc.) are used. All 6 RFC 6902 operations are implemented manually against plain Python dicts. RFC 6902 operations: add — set value at path (creates intermediate keys as needed for "" root; for list indices, appends if index == "-") remove — delete value at path (must exist) replace — set value at path (must already exist) move — remove from "from" path + add at "path" copy — copy value from "from" path to "path" test — assert that value at path equals "value"; raise PatchConflictError if not # VERIFICATION_STAMP # Story: 6.01 # Verified By: parallel-builder # Verified At: 2026-02-25 # Tests: 10/10 # Coverage: 100% ) annotationsN) dataclass)datetime)AnyListOptional>addcopymovetestremovereplaceset VALID_OPSc$eZdZdZdfd ZxZS)PatchConflictErrorz/Raised when an RFC 6902 'test' operation fails.c`||_||_||_t|d|d|d|y)NzPatch conflict at z : expected z, got )pathexpectedactualsuper__init__)selfrrr __class__s 3/mnt/e/genesis-system/core/coherence/state_delta.pyrzPatchConflictError.__init__6s;      k(VF: N )rstrrrrrreturnNone)__name__ __module__ __qualname____doc__r __classcell__)rs@rrr3s9  rrc|dk(rgS|jdstd|d|ddjd}|Dcgc]$}|jddjdd &c}Scc}w) a5 Convert an RFC 6902 JSON Pointer path to a list of keys/indices. Examples: "" -> [] "/" -> [""] "/a" -> ["a"] "/a/b" -> ["a", "b"] "/a/0/b" -> ["a", "0", "b"] Tilde escaping per RFC 6901: "~1" -> "/" "~0" -> "~" /zInvalid JSON Pointer path: u — must start with '/'Nz~1z~0~) startswith ValueErrorsplitr)rtokensts r _parse_pathr/Dsr rz ??3 6th>VWXX !"X^^C F=C DAIIdC ( (s 3 DD Ds)A,c|}|D]w}t|tr||vr t|||}(t|trt |t |d}||}Utdt |jd||S)zu Traverse obj along keys and return the final value. Raises KeyError / IndexError if any key is missing. F allow_appendzCannot traverse into z with key ) isinstancedictKeyErrorlist _list_indexlentyper )objkeyscurrentkeyidxs r_get_atr?\s G ^ gt $'!sm#clG  &c3ws r_set_atrGos XYY S$s) $FRI&$!y FD !)S[tD #f+  MM% F3K,T&\-B-B,CDEErcV|s tdt||dd}|d}t|tr ||vr t ||j |St|t r(t|t|d}|j |Stdt|j)z Remove and return the value at keys[-1] in obj (traversing keys[:-1]). Mutates obj in-place (caller must pass a deep copy). Raises KeyError / IndexError if path does not exist. zCannot remove root valueNrAFr1zCannot remove key from ) r+r?r3r4r5popr6r7r8rCr9r )r:r;rErFr>s r _remove_atrJs 344 S$s) $FRI&$ F "9% %zz)$$ FD !)S[uEzz#1$v,2G2G1HIJJrc|dk(r|r|Std t|}|dks||k\rtd|d|d|S#t$rtd|wxYw)z Convert a string key to a list index. "-" means append (index == length) when allow_append=True. Raises IndexError for out-of-range or ValueError for non-integer. -z/'-' index not allowed for get/remove operationszInvalid list index: rz List index z out of range (length )) IndexErrorintr+r5)r=lengthr2r>s rr7r7s  cz MJKK7#h Qw#-;se+A&KLL J 7-cW5667s ?Ac@t|ttfsy|D]}t|tsyd|vry|d}|tvryd|vst|j dt sy|dvr%d|vst|j dt sy|dvs}d|vsyy) u& Validate an RFC 6902 patch (list of operation dicts). Returns True if the patch is structurally valid, False otherwise. Does NOT raise — validation failures return False. Rules: - patch must be a list - every element must be a dict - every dict must have "op" key - "op" value must be in VALID_OPS - "path" key must be present and be a string - "move" and "copy" ops require a "from" key - "add", "replace", "test" ops require a "value" key - "remove" does NOT require "value" Fopr)r r from)r rr rDT)r3r6tupler4rgetr)patchop_dictrRs rvalidate_patchrXs" edE] +'4( w  T] Y   7;;v3F(L ! !W$Jw{{67JC,P + +g% rc tj|}|D]}|jd}|tvrt d||jdd}t |}|dk(r&|d} t ||}||k7set||||dk(r+tj|d} |s| }t||| |d k(r|s t d t|||d k(rL|stj|d}t ||t||tj|d|d k(r1|d } t | } t|| } |s| }:t||| I|dk(sP|d } t | } tjt || } |s| }t||| |S#ttf$r t}YPwxYw)a Apply an RFC 6902 patch to state dict. Returns a NEW dict (original unchanged). Supported operations: add, remove, replace, move, copy, test Raises: PatchConflictError: if "test" op fails (value mismatch) KeyError: if path does not exist for remove/replace/test ValueError: if patch is structurally invalid TypeError: if an operation targets a non-container rRz Unknown op: rr&r rD)rrrr r z!Cannot 'remove' the root documentrr rSr ) r deepcopyrUrr+r/r?r5rN_MISSINGrrGrJ)staterVresultrWrRrr;rrrD from_path from_keys moved_value copied_values r apply_patchrbs]]5 !F74 [[  Y |B623 3{{62&4  <w'H " .!(dXfUU 5[MM''"23Ee, 8^ !DEE vt $ 9_ww'78%dmmGG4D&EF 6\I#I.I$VY7K$k2 6\I#I.I==)CDL%l3o74r M[j) "! "s+ F//GGceZdZdZy) _MissingTypecy)Nz )rs r__repr__z_MissingType.__repr__+srN)r r!r"rgrfrrrdrd*srrdT)frozencLeZdZUdZded<ded<ded<ded<d ed <d d Zy ) StateDeltaur Immutable proposal for a state change, expressed as an RFC 6902 JSON Patch. Attributes: agent_id: ID of the agent proposing this change session_id: Session this change belongs to version_at_read: The state version this patch was built against patch: Tuple of RFC 6902 operation dicts (frozen for hashability) submitted_at: When this delta was submitted The patch field uses a tuple (not list) so the frozen dataclass remains hashable. Convert to list before calling apply_patch if needed — or use the convenience method apply_to(). ragent_id session_idrOversion_at_readrTrVr submitted_atc@t|t|jS)aJ Apply this delta's patches to state dict. Returns a NEW dict. The original state dict is never mutated. Raises: PatchConflictError: if a 'test' operation fails KeyError: if a required path does not exist ValueError: if the patch is malformed )rbr6rV)rr\s rapply_tozStateDelta.apply_toNs5$tzz"233rN)r\r4rr4)r r!r"r#__annotations__rprfrrrjrj7s) MO L 4rrj)rrrr6)r:rr;r6rr)r:rr;r6rDrrr)r=rrPrOr2boolrrO)rVr6rrr)r\r4rVr6rr4)r# __future__rr dataclassesrrtypingrrrrrq Exceptionrr/r?rGrJr7rXrbrdr[rjrfrrrws@# !&& F 3E    "E0&F.K*0#VHX > $ 4 4 4r