semora-store 0.1.0__tar.gz

semora_store-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.coverage
+htmlcov/
+.env
+.env.*
+!.env.example
+
+
+# Local tool/editor state — machine-specific, never pushed.
+.claude/
+.codecanvas/
+.vscode/
+
+
+# Superpowers design/spec scratch — working notes, not project documentation.
+docs/superpowers/
+
+# 로컬 자격증명 — 절대 커밋 금지.
+a.txt
+*.token

semora_store-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.5
+Name: semora-store
+Version: 0.1.0
+Summary: Storage-semantic contracts for Semora execution and append-only transcripts.
+Project-URL: Homepage, https://github.com/donggyun112/semora
+Project-URL: Source, https://github.com/donggyun112/semora
+Project-URL: Changelog, https://github.com/donggyun112/semora/blob/main/CHANGELOG.md
+Author: donggyun112
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.12

semora_store-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "semora-store"
+version = "0.1.0"
+description = "Storage-semantic contracts for Semora execution and append-only transcripts."
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "donggyun112" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+urls = { Homepage = "https://github.com/donggyun112/semora", Source = "https://github.com/donggyun112/semora", Changelog = "https://github.com/donggyun112/semora/blob/main/CHANGELOG.md" }
+dependencies = []
+# Deliberately empty, and the reason this is its own distribution. Storage adapters implement
+# behavior contracts over opaque values, so they need no message type, control point, or physical
+# schema from `semora`. Anything appearing here means the boundary moved.
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/semora_store"]

semora_store-0.1.0/src/semora_store/__init__.py

@@ -0,0 +1,44 @@
+"""Expose dependency-free step-ledger and transcript contracts."""
+
+from .context import ExecutionContext, ScopedStore
+from .ledger import (
+    Contended,
+    EffectCompletion,
+    EffectConflict,
+    ExecutionStore,
+    ExecutionTransition,
+    Fenced,
+    Indeterminate,
+    InputRecord,
+    MemorySteps,
+    Step,
+    StepLog,
+)
+from .transcript import (
+    MODEL_USAGE_FIELDS,
+    RUN_FIELDS,
+    MemoryTranscript,
+    Transcript,
+    check_fields,
+)
+
+__all__ = [
+    "MODEL_USAGE_FIELDS",
+    "RUN_FIELDS",
+    "Contended",
+    "EffectCompletion",
+    "EffectConflict",
+    "ExecutionContext",
+    "ExecutionStore",
+    "ExecutionTransition",
+    "Fenced",
+    "Indeterminate",
+    "InputRecord",
+    "MemorySteps",
+    "MemoryTranscript",
+    "ScopedStore",
+    "Step",
+    "StepLog",
+    "Transcript",
+    "check_fields",
+]

semora_store-0.1.0/src/semora_store/context.py

@@ -0,0 +1,38 @@
+"""Trusted, storage-neutral scope for one execution."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Protocol, Self
+
+__all__ = ["ExecutionContext", "ScopedStore"]
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionContext:
+    """Carry host-authenticated execution identity without interpreting tenant metadata.
+
+    ``run_id`` is Semora's execution and idempotency coordinate. Every other field is opaque to the
+    framework and must originate at the host trust boundary, never in model output or tool input.
+    """
+
+    run_id: str
+    session_id: str | None = None
+    namespace: str | None = None
+    actor: str | None = None
+    subject: str | None = None
+    attributes: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Freeze a copy so caller mutation cannot change authority mid-run."""
+        if not self.run_id:
+            raise ValueError("execution context requires a non-empty run_id")
+        object.__setattr__(self, "attributes", MappingProxyType(dict(self.attributes)))
+
+
+class ScopedStore(Protocol):
+    """Bind a trusted execution scope without prescribing an adapter's physical layout."""
+
+    def for_execution(self, context: ExecutionContext) -> Self:
+        """Return an adapter view bound to ``context``."""
+        ...

semora_store-0.1.0/src/semora_store/ledger.py

@@ -0,0 +1,365 @@
+"""Define the durable step ledger and its in-memory implementation.
+
+The ledger records opaque step values and distinguishes absent, running, and completed steps.
+It surfaces ambiguous interrupted effects instead of claiming exactly-once execution.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from time import monotonic
+from typing import Any, Literal, NamedTuple, Protocol, Self, runtime_checkable
+
+from .context import ExecutionContext, ScopedStore
+
+__all__ = [
+    "Contended",
+    "EffectCompletion",
+    "EffectConflict",
+    "ExecutionStore",
+    "ExecutionTransition",
+    "Fenced",
+    "Indeterminate",
+    "InputRecord",
+    "MemorySteps",
+    "Step",
+    "StepLog",
+]
+
+
+class Fenced(Exception):
+    """Report a write attempted with a stale fencing token."""
+
+    def __init__(self, run_id: str, presented: int, issued: int) -> None:
+        """Initialize the error with the stale and current tokens."""
+        super().__init__(
+            f"run {run_id!r} moved on: write presented token {presented}, current is {issued}"
+        )
+        self.run_id = run_id
+        self.presented = presented
+        self.issued = issued
+
+class Contended(Exception):
+    """Report that another worker holds the run lease."""
+
+    def __init__(self, run_id: str) -> None:
+        """Initialize the error for the contended run."""
+        super().__init__(f"run {run_id!r} is held by another worker")
+        self.run_id = run_id
+
+class Indeterminate(Exception):
+    """Report a step whose external effect may have occurred."""
+
+    def __init__(self, run_id: str, step: str) -> None:
+        """Initialize the error for the interrupted step."""
+        super().__init__(f"step {step!r} of run {run_id!r} may or may not have happened")
+        self.run_id = run_id
+        self.step = step
+
+
+class EffectConflict(Exception):
+    """Report an effect completion that contradicts its durable state."""
+
+    def __init__(self, run_id: str, key: str, reason: str) -> None:
+        """Initialize the conflict with its durable coordinates."""
+        super().__init__(f"effect {key!r} of run {run_id!r} cannot complete: {reason}")
+        self.run_id = run_id
+        self.key = key
+        self.reason = reason
+
+class Step(NamedTuple):
+    """Represent the persisted state and value of one step."""
+
+    status: Literal["absent", "running", "done"]
+    value: Any = None
+
+class InputRecord(NamedTuple):
+    """Represent one durable input queue row."""
+
+    input_id: str
+    status: Literal["pending", "claimed", "admitted", "discarded"]
+    value: dict[str, Any]
+    sequence: int
+
+
+class EffectCompletion(NamedTuple):
+    """Complete one immutable effect from the state that authorized the transition."""
+
+    key: str
+    value: Any
+    expected: Literal["absent", "running"] = "running"
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionTransition:
+    """Atomically commit effect results, mutable control state, and queued inputs."""
+
+    effects: tuple[EffectCompletion, ...] = ()
+    controls: Mapping[str, Any] = field(default_factory=dict)
+    inputs: tuple[tuple[str, dict[str, Any]], ...] = ()
+
+@runtime_checkable
+class ExecutionStore(ScopedStore, Protocol):
+    """Persist effect intent, control transitions, run leases, and queued inputs.
+
+    Implementations commit ``start`` before an effect executes and ``finish_effect`` afterward.
+    Completed effect results are immutable. Mutable continuation and protocol state uses
+    ``write_control`` or ``commit_transition`` instead. Lease-protected writes use the fencing
+    token returned by ``acquire``.
+    """
+
+    async def read(self, run_id: str, key: str) -> Step:
+        """Return the persisted state of a step."""
+        ...
+
+    async def start(self, run_id: str, key: str, token: int = 0) -> bool:
+        """Atomically record new step intent and report whether this caller inserted it."""
+        ...
+
+    async def finish_effect(self, run_id: str, key: str, value: Any, token: int = 0) -> None:
+        """Complete a running effect idempotently without replacing a committed result."""
+        ...
+
+    async def write_control(self, run_id: str, key: str, value: Any, token: int = 0) -> None:
+        """Upsert mutable framework control state."""
+        ...
+
+    async def acquire(self, run_id: str, owner: str, ttl_seconds: float) -> int:
+        """Acquire or renew a run lease and return its fencing token, or zero on contention."""
+        ...
+
+    async def release(self, run_id: str, owner: str) -> None:
+        """Release a run lease held by ``owner``."""
+        ...
+
+    async def enqueue_input(self, run_id: str, input_id: str, value: dict[str, Any]) -> bool:
+        """Append an input idempotently and report whether it was inserted."""
+        ...
+
+    async def list_inputs(self, run_id: str) -> list[InputRecord]:
+        """Return a run's inputs in submission order."""
+        ...
+
+    async def claim_input(self, run_id: str, input_id: str, token: int = 0) -> None:
+        """Mark an input as claimed unless it is already terminal."""
+        ...
+
+    async def admit_inputs(self, run_id: str, input_ids: list[str], token: int = 0) -> None:
+        """Mark the selected inputs as admitted to model context."""
+        ...
+
+    async def discard_inputs(self, run_id: str, input_ids: list[str], token: int = 0) -> None:
+        """Mark screened-out inputs as permanently discarded."""
+        ...
+
+    async def commit_transition(
+        self,
+        run_id: str,
+        transition: ExecutionTransition,
+        token: int = 0,
+    ) -> set[str]:
+        """Atomically apply typed effect, control, and input changes."""
+        ...
+
+    async def forget(self, run_id: str, key: str, token: int = 0) -> None:
+        """Remove an unfinished step. A `done` step is left alone.
+
+        Not optional, because clearing is what makes a reported failure retryable: a step that
+        raises, a model request that failed before its first chunk, and an aborted stream all end
+        by removing their intent. A ledger that silently kept them would turn every one of those
+        into a permanent `Indeterminate`.
+
+        Lease-protected like every other write, and for the sharper reason: erasing intent is the
+        one write that can make a *live* worker's step look like it never happened. A replaced
+        worker clearing its own abandoned attempt would otherwise delete the successor's running
+        intent, and the effect the successor is mid-way through would replay on the attempt after.
+        """
+        ...
+
+
+StepLog = ExecutionStore
+"""Compatibility name for the execution-store contract."""
+
+
+class MemorySteps:
+    """Implement ``ExecutionStore`` with process-local dictionaries."""
+
+    def __init__(self) -> None:
+        """Initialize empty step, lease, and input stores."""
+        self._entries: dict[tuple[str, str], Step] = {}
+        self._leases: dict[str, tuple[str, int, float]] = {}
+        self._tokens: dict[str, int] = {}
+        self._inputs: dict[tuple[str, str], InputRecord] = {}
+        self._input_sequence: dict[str, int] = {}
+
+    def for_execution(self, context: ExecutionContext) -> Self:
+        """Return this scope-neutral in-memory store."""
+        del context
+        return self
+
+    async def read(self, run_id: str, key: str) -> Step:
+        """Return the stored step or an absent state."""
+        return self._entries.get((run_id, key), Step("absent"))
+
+    async def start(self, run_id: str, key: str, token: int = 0) -> bool:
+        """Record running intent only when the step is absent."""
+        self._fence(run_id, token)
+        if (run_id, key) in self._entries:
+            return False
+        self._entries[run_id, key] = Step("running")
+        return True
+
+    async def finish_effect(self, run_id: str, key: str, value: Any, token: int = 0) -> None:
+        """Complete a running effect while preserving an existing result."""
+        self._fence(run_id, token)
+        record = self._entries.get((run_id, key), Step("absent"))
+        if record.status == "done":
+            if record.value == value:
+                return
+            raise EffectConflict(run_id, key, "a different result is already committed")
+        if record.status != "running":
+            raise EffectConflict(run_id, key, f"expected 'running', found {record.status!r}")
+        self._entries[run_id, key] = Step("done", value)
+
+    async def write_control(self, run_id: str, key: str, value: Any, token: int = 0) -> None:
+        """Upsert mutable process-local control state."""
+        self._fence(run_id, token)
+        self._entries[run_id, key] = Step("done", value)
+
+    async def finish(self, run_id: str, key: str, value: Any, token: int = 0) -> None:
+        """Compatibility alias for ``write_control``."""
+        await self.write_control(run_id, key, value, token)
+
+    async def forget(self, run_id: str, key: str, token: int = 0) -> None:
+        """Remove unfinished step intent while preserving completed results."""
+        self._fence(run_id, token)
+        if self._entries.get((run_id, key), Step("absent")).status != "done":
+            self._entries.pop((run_id, key), None)
+
+    async def acquire(self, run_id: str, owner: str, ttl_seconds: float = 60.0) -> int:
+        """Acquire or renew a run lease using a monotonic TTL.
+
+        Returns:
+            Current fencing token, or ``0`` when another owner holds the lease.
+        """
+        held = self._leases.get(run_id)
+        expired = held is not None and held[2] <= monotonic()
+        if held is not None and held[0] == owner:
+            self._leases[run_id] = (owner, held[1], monotonic() + ttl_seconds)
+            return held[1]  # the holder renewing keeps its token
+        if held is not None and not expired:
+            return 0
+        # A new lease or a takeover. Either way the token moves, so a previous holder is fenced.
+        self._tokens[run_id] = self._tokens.get(run_id, 0) + 1
+        self._leases[run_id] = (owner, self._tokens[run_id], monotonic() + ttl_seconds)
+        return self._tokens[run_id]
+
+    async def release(self, run_id: str, owner: str) -> None:
+        """Expire an owned lease without resetting its fencing token."""
+        held = self._leases.get(run_id)
+        if held is not None and held[0] == owner:
+            self._leases[run_id] = ("", held[1], monotonic())
+
+    async def enqueue_input(self, run_id: str, input_id: str, value: dict[str, Any]) -> bool:
+        """Append an input unless its identifier already exists."""
+        key = (run_id, input_id)
+        if key in self._inputs:
+            return False
+        sequence = self._input_sequence.get(run_id, 0)
+        self._input_sequence[run_id] = sequence + 1
+        self._inputs[key] = InputRecord(input_id, "pending", value, sequence)
+        return True
+
+    async def list_inputs(self, run_id: str) -> list[InputRecord]:
+        """Return a run's inputs in submission order."""
+        return sorted(
+            (record for (item_run, _), record in self._inputs.items() if item_run == run_id),
+            key=lambda record: record.sequence,
+        )
+
+    async def claim_input(self, run_id: str, input_id: str, token: int = 0) -> None:
+        """Mark an input as claimed unless it is already terminal."""
+        self._fence(run_id, token)
+        key = (run_id, input_id)
+        # Absent is a no-op, not a `KeyError`: the durable store expresses this as an `update` that
+        # matches no row, and a caller claiming an input that is already gone must not crash on one
+        # store and continue on the other.
+        record = self._inputs.get(key)
+        if record is not None and record.status not in {"admitted", "discarded"}:
+            self._inputs[key] = InputRecord(input_id, "claimed", record.value, record.sequence)
+
+    async def admit_inputs(self, run_id: str, input_ids: list[str], token: int = 0) -> None:
+        """Mark the selected inputs as admitted."""
+        self._fence(run_id, token)
+        for input_id in input_ids:
+            key = (run_id, input_id)
+            record = self._inputs.get(key)
+            if record is not None and record.status != "discarded":
+                self._inputs[key] = InputRecord(
+                    input_id, "admitted", record.value, record.sequence
+                )
+
+    async def discard_inputs(self, run_id: str, input_ids: list[str], token: int = 0) -> None:
+        """Make screened-out inputs terminal without deleting their idempotency keys."""
+        self._fence(run_id, token)
+        for input_id in input_ids:
+            key = (run_id, input_id)
+            record = self._inputs.get(key)
+            if record is not None:
+                self._inputs[key] = InputRecord(
+                    input_id, "discarded", record.value, record.sequence
+                )
+
+    async def commit_transition(
+        self,
+        run_id: str,
+        transition: ExecutionTransition,
+        token: int = 0,
+    ) -> set[str]:
+        """Atomically apply a process-local control transition."""
+        self._fence(run_id, token)
+        completed: list[tuple[str, Any]] = []
+        seen: set[str] = set()
+        for effect in transition.effects:
+            if effect.key in seen:
+                raise ValueError(f"effect {effect.key!r} appears twice in one transition")
+            seen.add(effect.key)
+            record = self._entries.get((run_id, effect.key), Step("absent"))
+            if record.status == "done":
+                if record.value != effect.value:
+                    raise EffectConflict(
+                        run_id, effect.key, "a different result is already committed"
+                    )
+                continue
+            if record.status != effect.expected:
+                raise EffectConflict(
+                    run_id,
+                    effect.key,
+                    f"expected {effect.expected!r}, found {record.status!r}",
+                )
+            completed.append((effect.key, effect.value))
+        overlap = seen.intersection(transition.controls)
+        if overlap:
+            raise ValueError(
+                f"transition classifies keys as both effect and control: {sorted(overlap)}"
+            )
+
+        inserted: set[str] = set()
+        for key, value in completed:
+            self._entries[run_id, key] = Step("done", value)
+        for key, value in transition.controls.items():
+            self._entries[run_id, key] = Step("done", value)
+        for input_id, value in transition.inputs:
+            input_key = (run_id, input_id)
+            if input_key in self._inputs:
+                continue
+            sequence = self._input_sequence.get(run_id, 0)
+            self._input_sequence[run_id] = sequence + 1
+            self._inputs[input_key] = InputRecord(input_id, "pending", value, sequence)
+            inserted.add(input_id)
+        return inserted
+
+    def _fence(self, run_id: str, token: int) -> None:
+        """Reject stale lease holders while allowing unleased writes with token zero."""
+        issued = self._tokens.get(run_id, 0)
+        if token and token < issued:
+            raise Fenced(run_id, token, issued)

semora_store-0.1.0/src/semora_store/transcript.py

@@ -0,0 +1,163 @@
+"""Claude-style transcript storage without prescribing a physical schema.
+
+One adapter owns the ordered conversation, branch markers, run lifecycle, and usage records. Entry
+mappings are opaque to the adapter boundary, so implementations may remap them to any tables,
+documents, or existing API as long as reads reconstruct the same transcript semantics.
+"""
+
+import json
+from typing import Any, NamedTuple, Protocol, Self, runtime_checkable
+
+from .context import ExecutionContext, ScopedStore
+
+__all__ = [
+    "MODEL_USAGE_FIELDS",
+    "RUN_FIELDS",
+    "MemoryTranscript",
+    "Transcript",
+]
+
+RUN_FIELDS = frozenset(
+    {
+        "conversation_id",
+        "stop_reason",
+        "tool_calls",
+        "interrupted_mid_turn",
+        "started_at",
+        "ended_at",
+    }
+)
+"""Fields accepted by run metadata records."""
+
+MODEL_USAGE_FIELDS = frozenset(
+    {
+        "prompt_tokens",
+        "completion_tokens",
+        "total_tokens",
+        "cached_tokens",
+        "cache_write_tokens",
+        "cost_usd",
+    }
+)
+"""Fields accepted by per-model usage records."""
+
+
+class _Row(NamedTuple):
+    """Store one transcript entry and its arrival order."""
+
+    seq: int
+    entry: dict[str, Any]
+
+
+@runtime_checkable
+class Transcript(ScopedStore, Protocol):
+    """Persist one ordered transcript while leaving its physical representation to the adapter."""
+
+    async def append(self, entry: dict[str, Any]) -> bool:
+        """Append an entry idempotently.
+
+        Args:
+            entry: Transcript entry containing ``conversation_id`` and ``uuid``.
+
+        Returns:
+            ``True`` when inserted, or ``False`` when the identity already exists.
+        """
+        ...
+
+    async def read(self, conversation_id: str, *, limit: int | None = None) -> list[dict[str, Any]]:
+        """Return entries in arrival order, optionally limited to the newest tail."""
+        ...
+
+    async def record_run(self, run_id: str, fields: dict[str, Any]) -> None:
+        """Merge validated lifecycle fields into this transcript's run record.
+
+        Raises:
+            ValueError: If ``fields`` contains a name outside ``RUN_FIELDS``.
+        """
+        ...
+
+    async def read_run(self, run_id: str) -> dict[str, Any] | None:
+        """The run record, or `None` if this run was never opened."""
+        ...
+
+    async def record_model_usage(self, run_id: str, model: str, counts: dict[str, Any]) -> None:
+        """Merge validated usage fields for one model in this transcript run.
+
+        Raises:
+            ValueError: If ``counts`` contains a name outside ``MODEL_USAGE_FIELDS``.
+        """
+        ...
+
+    async def read_model_usage(self, run_id: str) -> dict[str, dict[str, Any]]:
+        """This run's token counts keyed by the model that spent them."""
+        ...
+
+
+def check_fields(table: str, fields: dict[str, Any], allowed: frozenset[str]) -> None:
+    """Raise ``ValueError`` when a record contains unsupported fields."""
+    unknown = set(fields) - allowed
+    if unknown:
+        raise ValueError(f"{table} has no field {sorted(unknown)}")
+
+
+class MemoryTranscript:
+    """Implement the complete transcript contract with process-local collections."""
+
+    def __init__(self) -> None:
+        """Initialize empty history collections."""
+        self._rows: dict[str, list[_Row]] = {}
+        self._seen: set[tuple[str, str]] = set()
+        self._runs: dict[str, dict[str, Any]] = {}
+        self._model_usage: dict[tuple[str, str], dict[str, Any]] = {}
+        self._sequence = 0
+
+    def for_execution(self, context: ExecutionContext) -> Self:
+        """Ignore routing metadata in this process-local adapter."""
+        del context
+        return self
+
+    async def append(self, entry: dict[str, Any]) -> bool:
+        """Append an entry unless its conversation already holds that `uuid`."""
+        conversation_id = str(entry.get("conversation_id", ""))
+        key = (conversation_id, str(entry.get("uuid", "")))
+        if key in self._seen:
+            return False
+        self._seen.add(key)
+        self._sequence += 1
+        self._rows.setdefault(conversation_id, []).append(_Row(self._sequence, _frozen(entry)))
+        return True
+
+    async def read(self, conversation_id: str, *, limit: int | None = None) -> list[dict[str, Any]]:
+        """Return entries in arrival order, optionally limited to the newest tail."""
+        rows = self._rows.get(conversation_id, [])
+        window = rows if limit is None else rows[len(rows) - limit :] if limit > 0 else []
+        return [_frozen(row.entry) for row in window]
+
+    async def record_run(self, run_id: str, fields: dict[str, Any]) -> None:
+        """Merge validated fields into a process-local run record."""
+        check_fields("run", fields, RUN_FIELDS)
+        self._runs.setdefault(run_id, {}).update(fields)
+
+    async def read_run(self, run_id: str) -> dict[str, Any] | None:
+        """Return a copied run record."""
+        row = self._runs.get(run_id)
+        return dict(row) if row is not None else None
+
+    async def record_model_usage(self, run_id: str, model: str, counts: dict[str, Any]) -> None:
+        """Merge validated token counts for one model of one run."""
+        check_fields("model usage", counts, MODEL_USAGE_FIELDS)
+        self._model_usage.setdefault((run_id, model), {}).update(counts)
+
+    async def read_model_usage(self, run_id: str) -> dict[str, dict[str, Any]]:
+        """Return this run's token counts per model."""
+        return {
+            model: dict(counts)
+            for (recorded, model), counts in self._model_usage.items()
+            if recorded == run_id
+        }
+
+
+def _frozen(entry: dict[str, Any]) -> dict[str, Any]:
+    """Return a JSON-compatible deep copy of an entry."""
+    copied: dict[str, Any] = json.loads(json.dumps(entry))
+    return copied