handcode 0.3.0rc1__py3-none-any.whl

agentctl/kernel/paths.py

@@ -0,0 +1,203 @@
+r"""Which files would this call write, and do any of them escape the workspace?
+
+Separate from `classify.py` on purpose. The classifier answers *what kind of
+effect is this* -- the question the ledger needs to decide whether replaying it
+is safe. This module answers *where does it land*, which is a question about
+authority, not about replay.
+
+`docs/0025` §4 draws that line:
+
+    the gate               stops an effect happening TWICE
+    confirmation           stops an effect happening AT ALL without a human
+
+Escalating `write_file(path="~/.ssh/authorized_keys")` to `DESTRUCTIVE` would
+have collapsed the two -- the ledger would then treat an ordinary idempotent
+write as unrecoverable, and a perfectly safe replay would start failing closed.
+`cp a.txt /tmp/b.txt` is not destructive. It is merely none of the agent's
+business. So the effect class stays honest and the *authorization* layer asks.
+
+## What counts as a write target
+
+Only things that are unambiguously write destinations:
+
+* the declared path argument of a structured tool (`write_file`, `edit`, ...)
+* a shell redirect target -- `> f`, `>> f`, `tee f`
+* arguments to commands whose entire purpose is to mutate a named file
+
+Read paths are deliberately NOT collected. `grep secret /etc/shadow` reads
+outside the workspace, which is a real concern and a different one
+(exfiltration, not authority over the machine); pretending this module covers
+it would be worse than not covering it.
+"""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path, PurePath
+
+from .ledger.models import ToolCall
+
+# Arguments that name a file, for structured (non-shell) tools.
+PATH_ARGS = ("path", "file_path", "filename", "file", "dest", "destination")
+
+# `> f`, `>> f`, `2> f` -- but not `2>&1`, which writes no file.
+_REDIRECT = re.compile(r"(?<![>&\-])>{1,2}(?![>&])\s*([^\s;&|<>]+)")
+
+# Commands whose named arguments ARE the thing being changed.
+_FILE_MUTATORS = re.compile(
+    r"^\s*(?:sudo\s+)?(rm|mv|cp|touch|chmod|chown|shred|truncate|tee|ln|mkdir"
+    r"|rmdir|install)\b(.*)$"
+)
+
+# `cp`, `mv` and friends take sources then ONE destination, and only the
+# destination is written. Collecting every operand would flag
+# `cp /etc/hosts ./local` -- a read from outside, copied in -- as an
+# unauthorised write, and a prompt that is wrong is worse than no prompt (§5).
+_LAST_OPERAND_ONLY = {"cp", "mv", "ln", "install"}
+
+# Not paths: flags, operators, and the shell's own punctuation.
+_NOT_A_PATH = re.compile(r"^(-|\d+$|&|\||;|<|>)")
+
+
+def write_targets(call: ToolCall, *, arg_key: str = "command") -> list[str]:
+    """Every path this call would write to. Best effort, biased to over-report.
+
+    A path reported here that is not really written costs one confirmation
+    prompt. A path missed here is an unauthorised write, so the bias is
+    deliberate -- but see the module docstring for what is out of scope.
+    """
+    out: list[str] = []
+
+    for name in PATH_ARGS:
+        if (v := call.args.get(name)) and isinstance(v, str):
+            out.append(v)
+
+    if isinstance(command := call.args.get(arg_key), str):
+        out.extend(_shell_write_targets(command))
+
+    seen: set[str] = set()
+    return [p for p in out if not (p in seen or seen.add(p))]
+
+
+def _shell_write_targets(command: str) -> list[str]:
+    """Redirect destinations and the operands of file-mutating commands."""
+    from .classify import Classifier          # same layer, no cycle at import
+
+    out: list[str] = []
+    for segment in Classifier._segments(command):
+        out.extend(_REDIRECT.findall(segment))
+        if m := _FILE_MUTATORS.match(segment):
+            operands = [
+                t for token in m.group(2).split()
+                if (t := token.strip("'\"")) and not _NOT_A_PATH.match(t)
+            ]
+            if m.group(1) in _LAST_OPERAND_ONLY:
+                operands = operands[-1:]
+            out.extend(operands)
+    return out
+
+
+def escapes(target: str, root: str | Path) -> bool:
+    """Does `target` resolve outside `root`?
+
+    Resolution is lexical, and that is a deliberate choice: `Path.resolve()`
+    follows symlinks, so a link planted inside the workspace would resolve
+    outside it and be reported -- correct -- but a link planted OUTSIDE could
+    resolve back in and be waved through. Lexical normalisation cannot be
+    tricked that way, at the cost of treating a benign symlink as an escape.
+
+    `~` is expanded first. Without that, `~/.bashrc` is a relative path and
+    looks like it sits safely inside the workspace, which is precisely the case
+    that prompted this module.
+    """
+    root_p = PurePath(os.path.abspath(str(root)))
+    expanded = os.path.expanduser(os.path.expandvars(target))
+
+    if not os.path.isabs(expanded):
+        expanded = os.path.join(str(root_p), expanded)
+
+    resolved = PurePath(os.path.normpath(expanded))
+    try:
+        resolved.relative_to(root_p)
+        return False
+    except ValueError:
+        return True
+
+
+#: Places a redirect can point that are not files anyone owns. `2>/dev/null`
+#: asked for confirmation as "writes outside the workspace" in a live pooled
+#: run, and with no terminal the prompt read EOF and refused it (`docs/0047`).
+#: Exact names only: `/dev/sda` is a device, not a sink, and stays reported.
+_SINKS = frozenset({"/dev/null", "/dev/stdout", "/dev/stderr", "/dev/tty",
+                    "nul", "nul:", "con"})
+
+
+def escaping_writes(call: ToolCall, root: str | Path | None) -> list[str]:
+    """Write targets that land outside `root`. Empty when `root` is None."""
+    if root is None:
+        return []
+    return [t for t in write_targets(call)
+            if t.lower() not in _SINKS and escapes(t, root)]
+
+
+# ── installs into the user's environment (docs/0047 §5, docs/0052) ─────
+#
+# A package install writes no file this module can name -- it writes into an
+# interpreter's site-packages, a global node_modules, /usr/bin -- so neither
+# `escaping_writes` nor the effect class caught it. A live run showed the
+# agent running `pip install pytest` on the host, unasked. It is not
+# destructive, and it is not the agent's business either: the same
+# authorization question as a write outside the workspace.
+_INSTALLERS = re.compile(
+    r"^\s*(?:sudo\s+)?(?:"
+    r"(?P<pip>(?:\S*[/\\])?(?:pip3?(?:\.\d+)?|python3?(?:\.\d+)?(?:\.exe)?\s+-m\s+pip))"
+    r"\s+install\b"
+    r"|uv\s+(?:pip\s+install|tool\s+install|add\s+--global)\b"
+    r"|pipx\s+(?:install|inject)\b"
+    r"|(?:npm|pnpm)\s+(?:install|i|add)\b(?=.*\s(?:-g|--global)\b)"
+    r"|yarn\s+global\s+add\b"
+    r"|(?:apt|apt-get|dnf|yum|apk|zypper)\s+(?:install|add)\b"
+    r"|pacman\s+-S\b"
+    r"|(?:brew|cargo|gem|conda|mamba|choco|winget|scoop)\s+install\b"
+    r"|go\s+install\b"
+    r")")
+
+
+def environment_installs(call: ToolCall, root: str | Path | None) -> list[str]:
+    """Shell segments that install software outside the workspace.
+
+    An install into an environment that lives INSIDE the workspace is not
+    flagged: `.venv/bin/pip install pytest`, `uv pip install --python
+    .venv/...`, or `pip install --target ./vendor` change only the repo, which
+    is the agent's to change. A plain `pip install` goes to whichever
+    interpreter is on PATH -- usually the user's own -- and is flagged.
+    """
+    command = call.args.get("command")
+    if not isinstance(command, str) or root is None:
+        return []
+    from .classify import Classifier          # same layer, no cycle at import
+
+    out = []
+    for segment in Classifier._segments(command):
+        m = _INSTALLERS.match(segment)
+        if not m:
+            continue
+        if _lands_inside(segment, m, root):
+            continue
+        out.append(segment.strip())
+    return out
+
+
+def _lands_inside(segment: str, m: re.Match, root) -> bool:
+    """Does this install target an environment inside the workspace?"""
+    # The installer itself lives in the workspace: `.venv/bin/pip`,
+    # `./venv/Scripts/python -m pip`.
+    exe = (m.group("pip") or "").split()[0] if m.group("pip") else ""
+    if exe and ("/" in exe or "\\" in exe) and not escapes(exe, root):
+        return True
+    # An explicit destination inside the workspace.
+    for flag in ("--target", "-t", "--prefix", "--root", "--python", "-p"):
+        if (d := re.search(rf"(?:^|\s){re.escape(flag)}[=\s]+(\S+)", segment)):
+            if not escapes(d.group(1).strip("'\""), root):
+                return True
+    return False

agentctl/kernel/policy.py

@@ -0,0 +1,160 @@
+r"""Read a compiled policy. Lookups only — no evaluation in-band.
+
+`docs/0012` §5.2: *"compiles to a flat lookup artifact the kernel reads from
+disk -- no evaluation logic in-band."* That sentence is the whole design, and
+it is the same trick as the capability matrix: the control plane does the
+thinking, writes an artifact, and the kernel reads it. A malformed policy fails
+where a human is watching, not in the middle of a run.
+
+So there is no YAML here, no schema, no merge, no defaults resolution, and no
+`if` on a pool name. Those live in `control/policy/compile.py`. If this module
+ever needs to *decide* something, the compiler should have decided it.
+
+## Budget, and why a cap can lie
+
+`docs/0021` §5 found litellm reports cost `0.0` for endpoints it cannot price,
+indistinguishable from a call that was genuinely free. A cap compared against
+measured spend therefore **under-blocks**: the real figure is higher than the
+one being checked, always in the direction of spending more than intended.
+
+The guard refuses to hide that. Every verdict carries the pricing coverage it
+was computed from, and what to do about incomplete coverage is a decision the
+policy states out loud (`on_unpriced`) rather than one this module makes
+quietly. The default is `warn`, which is fail-open — consistent with
+`docs/0008` §6.5, where cost and routing fail open and only effect decisions
+fail closed. Choosing `block` is available and is a real trade: it stops work
+when measurement is incomplete, which on a free-tier pool is most of the time.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+DEFAULT_POLICY = (
+    Path(__file__).resolve().parent.parent
+    / "control" / "policy" / "data" / "policy.compiled.json"
+)
+
+
+@dataclass(frozen=True)
+class BudgetVerdict:
+    """What the budget says, and how much to trust it."""
+    allowed: bool
+    reason: str
+    scope: str = ""                 # "per_task" | "daily"
+    spent_usd: float = 0.0
+    limit_usd: float | None = None
+    coverage: float = 1.0           # share of calls that could be priced
+
+    @property
+    def trustworthy(self) -> bool:
+        return self.coverage >= 1.0
+
+    def describe(self) -> str:
+        if self.limit_usd is None:
+            return "no budget configured"
+        base = f"${self.spent_usd:.4f} of ${self.limit_usd:.2f} ({self.scope})"
+        if not self.trustworthy:
+            # Never print a spend figure without saying what it omits.
+            return (f"{base} — but only {self.coverage:.0%} of calls could be "
+                    f"priced, so the real spend is HIGHER")
+        return base
+
+
+class Policy:
+    """A compiled policy artifact. Every method is a lookup."""
+
+    def __init__(self, data: dict | None = None):
+        self._d: dict = data or {}
+
+    @classmethod
+    def load(cls, path: str | Path | None = None) -> "Policy":
+        p = Path(path or DEFAULT_POLICY)
+        if not p.exists():
+            raise FileNotFoundError(
+                f"no compiled policy at {p}\n"
+                f"  compile one:  agentctl policy <policy.yaml>")
+        return cls(json.loads(p.read_text(encoding="utf-8")))
+
+    @classmethod
+    def empty(cls) -> "Policy":
+        """No policy. Every lookup returns nothing, and nothing is enforced."""
+        return cls({})
+
+    def __bool__(self) -> bool:
+        return bool(self._d)
+
+    # ── effects ────────────────────────────────────────────────────────
+    def effect_rule(self, effect_class: str) -> str | None:
+        """e.g. DESTRUCTIVE -> "require_human_approval"."""
+        return (self._d.get("effects") or {}).get(str(effect_class))
+
+    def requires_approval(self, effect_class: str) -> bool:
+        return self.effect_rule(effect_class) == "require_human_approval"
+
+    # ── budget ─────────────────────────────────────────────────────────
+    def limit(self, scope: str) -> float | None:
+        return (self._d.get("budget") or {}).get(f"{scope}_usd")
+
+    @property
+    def on_exceeded(self) -> str:
+        return (self._d.get("budget") or {}).get("on_exceeded", "block")
+
+    @property
+    def on_unpriced(self) -> str:
+        return (self._d.get("budget") or {}).get("on_unpriced", "warn")
+
+    def check_budget(self, spent_usd: float, scope: str = "per_task",
+                     coverage: float = 1.0) -> BudgetVerdict:
+        """Is there room left? The spend is SUPPLIED, never fetched.
+
+        The cost ledger lives in the control plane and the kernel may not
+        import it (`docs/0008` R2), which is not an inconvenience here but the
+        right shape: a guard that queried a database in-band would fail when
+        the control plane is down, and this must not.
+        """
+        limit = self.limit(scope)
+        if limit is None:
+            return BudgetVerdict(True, "no budget configured", scope,
+                                 spent_usd, None, coverage)
+
+        v = BudgetVerdict(spent_usd < limit, "", scope, spent_usd, limit, coverage)
+
+        if spent_usd >= limit:
+            if self.on_exceeded == "warn":
+                return BudgetVerdict(True, f"over budget ({v.describe()}), "
+                                     f"policy says warn", scope, spent_usd,
+                                     limit, coverage)
+            return BudgetVerdict(False, f"budget exceeded: {v.describe()}",
+                                 scope, spent_usd, limit, coverage)
+
+        # Under the cap on paper. If the measurement is incomplete the real
+        # figure is higher, and saying nothing would be the wrong silence.
+        if coverage < 1.0 and self.on_unpriced == "block":
+            return BudgetVerdict(
+                False,
+                f"only {coverage:.0%} of calls could be priced and policy says "
+                f"block; measured {v.describe()}",
+                scope, spent_usd, limit, coverage)
+
+        return BudgetVerdict(True, v.describe(), scope, spent_usd, limit,
+                             coverage)
+
+    # ── routing (read-only; the compiler resolved it) ───────────────────
+    @property
+    def default_pool(self) -> str | None:
+        return (self._d.get("routing") or {}).get("default_pool")
+
+    def pool(self, name: str) -> list[str]:
+        return list(((self._d.get("routing") or {}).get("pools") or {}).get(name, []))
+
+    @property
+    def escalation(self) -> dict[str, Any]:
+        return dict((self._d.get("routing") or {}).get("escalation") or {})
+
+    @property
+    def source_sha256(self) -> str:
+        """Which policy.yaml this was compiled from. For `agentctl policy show`."""
+        return self._d.get("source_sha256", "")

agentctl/kernel/reconcile/__init__.py

@@ -0,0 +1,31 @@
+"""Reconciliation probes: ask the world whether an effect already landed."""
+from .base import (
+    DID_NOT_LAND,
+    INCONCLUSIVE,
+    LANDED,
+    SAFE_TO_RETRY,
+    ProbeRegistry,
+    ReconciliationProbe,
+)
+from .external import IdempotencyProbe
+from .filesystem import FileAppendProbe
+from .git import GitProbe
+
+__all__ = [
+    "DID_NOT_LAND", "INCONCLUSIVE", "LANDED", "SAFE_TO_RETRY",
+    "ProbeRegistry", "ReconciliationProbe",
+    "FileAppendProbe", "GitProbe", "IdempotencyProbe",
+]
+
+
+def default_registry(repo_root=None, idempotency_fields=None) -> ProbeRegistry:
+    """The probes worth having on by default.
+
+    Order matters for auto-selection: the specific probes are tried before the
+    idempotency one, which handles any call carrying a key.
+    """
+    return ProbeRegistry(
+        GitProbe(repo_root),
+        FileAppendProbe(),
+        IdempotencyProbe(idempotency_fields),
+    )

agentctl/kernel/reconcile/base.py

@@ -0,0 +1,106 @@
+"""Reconciliation probes. Spec: `docs/0012` §3.3, revised.
+
+The problem: after a crash we hold an `INTENT` record and cannot tell whether
+the effect landed. A probe asks the world.
+
+**Design change from `docs/0012` §3.3.** That section specified injecting the
+intent hash into the effect itself (a git trailer), which requires mutating the
+command before execution — only possible at Seam C. This uses *world
+fingerprinting* instead:
+
+    capture()  before execution   -> record what the world looked like
+    probe()    after a crash      -> compare; did it change?
+
+That needs no cooperation from the tool, works at Seam B, and generalises to
+effects that have nowhere to carry a marker.
+
+Remote effects cannot be fingerprinted this way — the world in question is
+somebody else's server. They are handled by a different mechanism entirely
+(`external.py`, `docs/0020`): make the retry *safe* rather than trying to
+determine whether it is *necessary*.
+
+**The assumption fingerprinting rests on**, stated plainly: the agent's
+workspace has a single writer. If a human commits to the same repo during the crash window, a
+probe can misread that as the agent's effect. Every probe returns
+`INCONCLUSIVE` rather than guessing when it can distinguish the cases, and the
+gate fails closed on `INCONCLUSIVE`.
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+LANDED = "LANDED"
+DID_NOT_LAND = "DID_NOT_LAND"
+INCONCLUSIVE = "INCONCLUSIVE"
+
+#: The effect may have landed, and it does not matter: the call carries an
+#: idempotency key, so re-sending it produces at most one effect at the remote
+#: end. Answering "did it land?" is impossible for a remote API and also the
+#: wrong question -- see `docs/0020`.
+SAFE_TO_RETRY = "SAFE_TO_RETRY"
+
+
+@runtime_checkable
+class ReconciliationProbe(Protocol):
+    """Answers 'did this effect already happen?' from outside the ledger."""
+
+    name: str
+
+    def handles(self, call) -> bool:
+        """Can this probe say anything about this call?"""
+
+    def capture(self, call) -> dict | None:
+        """Fingerprint the world BEFORE execution.
+
+        Returns a JSON-serialisable dict stored on the INTENT record, or None
+        if nothing useful can be captured. Must never raise — a probe that
+        explodes here would block the call entirely.
+        """
+
+    def probe(self, call, record) -> str:
+        """LANDED | DID_NOT_LAND | SAFE_TO_RETRY | INCONCLUSIVE.
+
+        Uses `record.pre_state`. Must never raise. When in doubt, return
+        INCONCLUSIVE and let the gate fail closed.
+        """
+
+
+class ProbeRegistry:
+    """Holds the probes and picks one per call."""
+
+    def __init__(self, *probes: ReconciliationProbe):
+        self._probes = list(probes)
+        self._by_name = {p.name: p for p in probes}
+
+    def add(self, probe: ReconciliationProbe) -> "ProbeRegistry":
+        self._probes.append(probe)
+        self._by_name[probe.name] = probe
+        return self
+
+    def get(self, name: str | None):
+        return self._by_name.get(name) if name else None
+
+    def for_call(self, call, name: str | None = None):
+        """Prefer the probe the capability matrix named; else the first match.
+
+        A *named* probe is trusted without consulting `handles()`. The matrix is
+        an operator declaration -- "this tool commits to git" -- and it knows
+        things a heuristic cannot: a dedicated `commit` tool carries no "git
+        commit" string in its arguments to sniff for.
+        """
+        if name and (p := self._by_name.get(name)) is not None:
+            return p
+        for p in self._probes:
+            if _safe_handles(p, call):
+                return p
+        return None
+
+    def __len__(self) -> int:
+        return len(self._probes)
+
+
+def _safe_handles(probe, call) -> bool:
+    try:
+        return bool(probe.handles(call))
+    except Exception:                                   # noqa: BLE001
+        return False

agentctl/kernel/reconcile/external.py

@@ -0,0 +1,137 @@
+"""Idempotency-key probe for EXTERNAL effects. `docs/0020`.
+
+Git and filesystem effects are fingerprintable: we look at the world before and
+after. A remote API is not — the world in question is somebody else's server,
+and we cannot see it without its cooperation.
+
+So this probe does not answer *"did it land?"*. It answers a different and
+better question:
+
+    Is it SAFE to send this again?
+
+If the call carries a stable idempotency key, the answer is yes regardless of
+what happened, because a compliant server collapses the retry into the original
+effect. That is the mechanism Stripe standardised, and it is the only general
+way to make a remote non-idempotent effect replay-safe.
+
+**This probe only works because the same key goes out twice.** Seam C stamps a
+key derived from the call's arguments before execution, so a crash and resume
+produce the same value. A key the model supplied itself is equally good. What
+the probe refuses is a request that carried *no* key, or a different one —
+there the remote has nothing to deduplicate against and the retry is simply a
+second effect.
+
+What this does *not* give you: the original response. A deduped retry returns
+the server's recorded response, which is usually what you want — but the agent
+sees the retry's return value, not the pre-crash one.
+"""
+from __future__ import annotations
+
+import json
+
+from .base import INCONCLUSIVE, SAFE_TO_RETRY
+
+#: Arguments a tool might already use for an idempotency key. Checked before
+#: falling back to whatever the capability matrix declares.
+_CONVENTIONAL_KEYS = (
+    "idempotency_key", "idempotencyKey", "request_id", "requestId",
+    "client_token", "clientToken", "dedupe_key", "dedupeKey",
+)
+
+
+class IdempotencyProbe:
+    """Declares a retry safe when the call carries a stable idempotency key.
+
+    Selection is deliberately conservative: it handles a call only when a key
+    field is present or the capability matrix names one. An EXTERNAL effect
+    with no key mechanism is left to fail closed, which is correct — there is
+    genuinely no safe way to retry it.
+    """
+
+    name = "idempotency"
+
+    def __init__(self, key_fields: dict[str, str] | None = None):
+        #: {tool_name: argument holding the key}, from the capability matrix.
+        self.key_fields = key_fields or {}
+
+    # ── selection ──────────────────────────────────────────────────────
+    def handles(self, call) -> bool:
+        return self.key_field(call) is not None
+
+    def key_field(self, call) -> str | None:
+        """Which argument carries the idempotency key for this call."""
+        declared = self.key_fields.get(call.tool_name)
+        if declared:
+            return declared
+        for k in _CONVENTIONAL_KEYS:
+            if k in call.args:
+                return k
+        return None
+
+    def key_for(self, call) -> str:
+        """The key we stamp when the call has none. Stable across a crash.
+
+        Derived from the arguments *excluding the key field itself* — deriving
+        it from arguments that contain it would be circular: stamping the key
+        changes the args, which changes the key.
+        """
+        import hashlib
+        import json as _json
+
+        field = self.key_field(call)
+        args = {k: v for k, v in call.args.items() if k != field}
+        canonical = _json.dumps({"t": call.tool_name, "a": args},
+                                sort_keys=True, separators=(",", ":"), default=str)
+        return f"agentctl-{hashlib.sha256(canonical.encode()).hexdigest()[:32]}"
+
+    # ── before ─────────────────────────────────────────────────────────
+    def capture(self, call) -> dict | None:
+        """Record the key that is actually going out with this request.
+
+        Not the key we would choose — the one on the call. A model-supplied
+        key is just as good, provided the same one is sent again.
+        """
+        field = self.key_field(call)
+        if field is None:
+            return None
+        present = str(call.args.get(field) or "")
+        return {
+            "probe": self.name,
+            "field": field,
+            # Empty means no key went out, so a retry would be a second effect.
+            # That happens on a Seam-B-only deployment, where nothing stamps.
+            "key": present,
+        }
+
+    # ── after a crash ──────────────────────────────────────────────────
+    def probe(self, call, record) -> str:
+        pre = _pre(record)
+        if not pre or pre.get("probe") != self.name:
+            return INCONCLUSIVE
+
+        field, sent = pre.get("field"), pre.get("key")
+        if not field:
+            return INCONCLUSIVE
+
+        # No key went out, so the remote has nothing to deduplicate against
+        # and a retry would be a second effect.
+        if not sent:
+            return INCONCLUSIVE
+
+        # The same key must go out again. Anything else -- a regenerated key, a
+        # changed argument that feeds it -- makes the retry a fresh request.
+        now = str(call.args.get(field) or "") or self.key_for(call)
+        if now != sent:
+            return INCONCLUSIVE
+
+        return SAFE_TO_RETRY
+
+
+def _pre(record) -> dict | None:
+    raw = getattr(record, "pre_state", None)
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except Exception:                                   # noqa: BLE001
+        return None