"""Remote write computation (contract.md §6.4, §15.2). Pure functions over JSON-shaped documents; no I/O. The plane runs the authoritative write check; the agent runs the same check before sending so a locked write fails with a clear message and nothing goes on the wire. """ from __future__ import annotations import copy from typing import Any, Dict, Iterator, List, Optional, Sequence, Tuple from .paths import Path, covers, encode Locks = Sequence[tuple[Path, str]] def json_equal(a: Any, b: Any) -> bool: """Structural JSON equality: numbers by value, but ``True`` is not ``1``.""" if isinstance(a, bool) or isinstance(b, bool): return type(a) is type(b) and a == b if isinstance(a, int | float) and isinstance(b, int | float): return a == b if isinstance(a, dict) and isinstance(b, dict): return a.keys() == b.keys() and all(json_equal(a[k], b[k]) for k in a) if isinstance(a, list) and isinstance(b, list): return len(a) == len(b) and all(json_equal(x, y) for x, y in zip(a, b)) return type(a) is type(b) and a == b def diff(base: dict[str, Any], new: dict[str, Any], prefix: Path = ()) -> tuple[dict[Path, Any], list[Path]]: """``(set, unset)`` turning ``base`` into ``new`` (§15.2 step 5). A changed list is one whole-list ``set`` (D8); a key equal to its base value is not sent.""" sets: dict[Path, Any] = {} unsets: list[Path] = [] for key, value in new.items(): p = prefix + (key,) if key not in base: sets[p] = value elif isinstance(base[key], dict) and isinstance(value, dict): s, u = diff(base[key], value, p) sets.update(s) unsets.extend(u) elif not json_equal(base[key], value): sets[p] = value unsets.extend(prefix + (key,) for key in base if key not in new) return sets, unsets def intent_diff(base: dict[str, Any], new: dict[str, Any], prefix: Path = ()) -> tuple[dict[Path, Any], list[Path]]: """:func:`diff` as a caller's *intent*: the key-level edit a write means, to be re-applied to a newer document after a CAS conflict (§15.3). A mapping the base did not hold as a mapping (absent, or a scalar) is expanded to its leaves: writing ``terminal.timeout`` into a profile with no ``terminal`` section means "set that key", not "replace whatever ``terminal`` holds by the time the retry runs" — another writer's ``terminal.persistent`` must survive it. Only an empty mapping stays a whole value (there is no leaf to name); :func:`apply_intent` adds it without replacing a mapping that appeared meanwhile.""" sets: dict[Path, Any] = {} unsets: list[Path] = [] for key, value in new.items(): p = prefix + (key,) old = base.get(key, _ABSENT) if isinstance(value, dict) and value and not isinstance(old, dict): s, _ = intent_diff({}, value, p) sets.update(s) elif key not in base: sets[p] = value elif isinstance(old, dict) and isinstance(value, dict): s, u = intent_diff(old, value, p) sets.update(s) unsets.extend(u) elif not json_equal(old, value): sets[p] = value unsets.extend(prefix + (key,) for key in base if key not in new) return sets, unsets _ABSENT = object() def apply_intent(doc: dict[str, Any], sets: dict[Path, Any], unsets: Sequence[Path]) -> None: """Apply an :func:`intent_diff` edit to *doc* in place.""" for p, v in sets.items(): if isinstance(v, dict) and not v: found, cur = _get_path(doc, p) if found and isinstance(cur, dict): continue # "make this a mapping": a mapping is already there, with its keys _set_path(doc, p, copy.deepcopy(v)) for p in unsets: _pop_path(doc, p) def _set_path(doc: dict[str, Any], path: Path, value: Any) -> None: node = doc for seg in path[:-1]: if not isinstance(node.get(seg), dict): node[seg] = {} node = node[seg] node[path[-1]] = value def _pop_path(doc: dict[str, Any], path: Path) -> bool: node: Any = doc for seg in path[:-1]: if not isinstance(node, dict) or not isinstance(node.get(seg), dict): return False node = node[seg] if isinstance(node, dict) and path[-1] in node: del node[path[-1]] return True return False def _get_path(doc: dict[str, Any], path: Path) -> tuple[bool, Any]: node: Any = doc for seg in path: if not isinstance(node, dict) or seg not in node: return False, None node = node[seg] return True, node def strip_locked(base: dict[str, Any], new: dict[str, Any], locks: Locks) -> tuple[dict[str, Any], dict[str, Any], list[Path]]: """Drop every locked path from BOTH documents (§15.2 step 1), so a bulk write neither sets nor unsets a key it may not touch. Returns the copies and the locked paths whose new value differed from the effective one (the ones the caller tried to change).""" base, new = copy.deepcopy(base), copy.deepcopy(new) changed: list[Path] = [] for lock, _level in locks: in_base, base_val = _get_path(base, lock) in_new, new_val = _get_path(new, lock) if in_base != in_new or (in_new and not json_equal(base_val, new_val)): changed.append(lock) _pop_path(base, lock) _pop_path(new, lock) return base, new, changed def _touched(path: Path, value: Any) -> Iterator[tuple[Path, Any]]: """``(touched path, value written there)`` for ``set path = value`` (§6.4 rule 2): the path itself and every path inside ``value``, descending through objects only.""" yield path, value if isinstance(value, dict): for k, v in value.items(): yield from _touched(path + (k,), v) def write_check(sets: dict[Path, Any], unsets: Sequence[Path], locks: Locks) -> Optional[tuple[Path, str]]: """The ``(lock path, level)`` that refuses this write (§6.4 rules 1-3), or None.""" for p in unsets: for lock, level in locks: if covers(lock, p): return lock, level for p, v in sets.items(): for t, tv in _touched(p, v): for lock, level in locks: if covers(lock, t): return lock, level # R7: a non-object written at a strict ancestor of a lock would replace the # locked subtree through deep merge. if len(t) < len(lock) and covers(t, lock) and not isinstance(tv, dict): return lock, level return None def encode_changes(sets: dict[Path, Any], unsets: Sequence[Path]) -> tuple[dict[str, Any], list[str]]: return {encode(p): v for p, v in sets.items()}, [encode(p) for p in unsets]