pycode-kg 0.25.0__tar.gz → 0.26.0__tar.gz

{pycode_kg-0.25.0 → pycode_kg-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.25.0
+Version: 0.26.0
 Summary: A tool to build a searchable knowledge graph from Python repositories
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -60,7 +60,7 @@ Description-Content-Type: text/markdown
 
 [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
 [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
-[![Version](https://img.shields.io/badge/version-0.25.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.26.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
 [![CI](https://github.com/Flux-Frontiers/pycode_kg/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/pycode_kg/actions/workflows/ci.yml)
 [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
 [![DOI](https://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
@@ -255,7 +255,7 @@ src/pycode_kg/
 └── viz3d_timeline.py                # Metric history timeline
 ```
 
-The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.25.0.md](docs/analysis_v0.25.0.md), produced (of course) by `pycodekg analyze` against this very repo.
+The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.26.0.md](docs/analysis_v0.26.0.md), produced (of course) by `pycodekg analyze` against this very repo.
 
 ---
 
@@ -282,13 +282,13 @@ If you use PyCodeKG in your research or project, please cite it:
 
 [![DOI](https://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
 
-> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.25.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.26.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
 
 ```bibtex
 @software{suchanek_pycode_kg,
   author    = {Suchanek, Eric G.},
   title     = {{PyCodeKG}: A Knowledge Graph for Python Codebases},
-  version   = {0.25.0},
+  version   = {0.26.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

{pycode_kg-0.25.0 → pycode_kg-0.26.0}/README.md

@@ -5,7 +5,7 @@
 
 [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
 [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
-[![Version](https://img.shields.io/badge/version-0.25.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.26.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
 [![CI](https://github.com/Flux-Frontiers/pycode_kg/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/pycode_kg/actions/workflows/ci.yml)
 [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
 [![DOI](https://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
@@ -200,7 +200,7 @@ src/pycode_kg/
 └── viz3d_timeline.py                # Metric history timeline
 ```
 
-The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.25.0.md](docs/analysis_v0.25.0.md), produced (of course) by `pycodekg analyze` against this very repo.
+The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.26.0.md](docs/analysis_v0.26.0.md), produced (of course) by `pycodekg analyze` against this very repo.
 
 ---
 
@@ -227,13 +227,13 @@ If you use PyCodeKG in your research or project, please cite it:
 
 [![DOI](https://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
 
-> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.25.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.26.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
 
 ```bibtex
 @software{suchanek_pycode_kg,
   author    = {Suchanek, Eric G.},
   title     = {{PyCodeKG}: A Knowledge Graph for Python Codebases},
-  version   = {0.25.0},
+  version   = {0.26.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

{pycode_kg-0.25.0 → pycode_kg-0.26.0}/pyproject.toml

@@ -70,7 +70,7 @@ torch = [
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.25.0"
+version = "0.26.0"
 description = "A tool to build a searchable knowledge graph from Python repositories"
 readme = "README.md"
 license = "Elastic-2.0"

{pycode_kg-0.25.0 → pycode_kg-0.26.0}/src/pycode_kg/__init__.py

@@ -36,7 +36,7 @@ Author: Eric G. Suchanek, PhD
 License: Elastic 2.0
 """
 
-__version__ = "0.25.0"
+__version__ = "0.26.0"
 __author__ = "Eric G. Suchanek, PhD"
 
 # Low-level primitives (locked v0 contract)

{pycode_kg-0.25.0 → pycode_kg-0.26.0}/src/pycode_kg/cli/cmd_snapshot.py

@@ -25,7 +25,12 @@ from pycode_kg.cli.options import sqlite_option
 from pycode_kg.kg import PyCodeKG
 from pycode_kg.pycodekg import DEFAULT_MODEL
 from pycode_kg.pycodekg_thorough_analysis import PyCodeKGAnalyzer
-from pycode_kg.snapshots import SnapshotManager
+from pycode_kg.snapshots import (
+    SnapshotDelta,
+    SnapshotManager,
+    delta_from_dict,
+    metrics_from_dict,
+)
 from pycode_kg.store import GraphStore
 
 
@@ -174,9 +179,10 @@ def save_snapshot(
     click.echo(f"OK Snapshot saved: {snapshot_file}")
     click.echo(f"  Key:     {snapshot_obj.key}")
     click.echo(f"  Version: {snapshot_obj.version}")
-    click.echo(f"  Nodes:   {snapshot_obj.metrics.total_nodes}")
-    click.echo(f"  Edges:   {snapshot_obj.metrics.total_edges}")
-    click.echo(f"  Coverage: {snapshot_obj.metrics.docstring_coverage:.1%}")
+    saved_metrics = metrics_from_dict(snapshot_obj.metrics)
+    click.echo(f"  Nodes:   {saved_metrics.total_nodes}")
+    click.echo(f"  Edges:   {saved_metrics.total_edges}")
+    click.echo(f"  Coverage: {saved_metrics.docstring_coverage:.1%}")
 
 
 @snapshot.command("list")
@@ -270,19 +276,20 @@ def show_snapshot(key: str, snapshots_dir: str | None) -> None:
     click.echo()
 
     click.echo("Metrics:")
-    click.echo(f"  Total Nodes:       {snapshot_obj.metrics.total_nodes}")
-    click.echo(f"  Total Edges:       {snapshot_obj.metrics.total_edges}")
-    click.echo(f"  Meaningful Nodes:  {snapshot_obj.metrics.meaningful_nodes}")
-    click.echo(f"  Docstring Coverage: {snapshot_obj.metrics.docstring_coverage:.1%}")
-    click.echo(f"  Critical Issues:   {snapshot_obj.metrics.critical_issues}")
-    click.echo(f"  Complexity Median: {snapshot_obj.metrics.complexity_median:.2f}")
+    metrics = metrics_from_dict(snapshot_obj.metrics)
+    click.echo(f"  Total Nodes:       {metrics.total_nodes}")
+    click.echo(f"  Total Edges:       {metrics.total_edges}")
+    click.echo(f"  Meaningful Nodes:  {metrics.meaningful_nodes}")
+    click.echo(f"  Docstring Coverage: {metrics.docstring_coverage:.1%}")
+    click.echo(f"  Critical Issues:   {metrics.critical_issues}")
+    click.echo(f"  Complexity Median: {metrics.complexity_median:.2f}")
     click.echo()
 
     click.echo("Node/Edge Breakdown:")
-    for kind, count in sorted(snapshot_obj.metrics.node_counts.items()):
+    for kind, count in sorted(metrics.node_counts.items()):
         click.echo(f"  {kind}: {count}")
     click.echo()
-    for rel, count in sorted(snapshot_obj.metrics.edge_counts.items()):
+    for rel, count in sorted(metrics.edge_counts.items()):
         click.echo(f"  {rel}: {count}")
     click.echo()
 
@@ -296,7 +303,7 @@ def show_snapshot(key: str, snapshots_dir: str | None) -> None:
 
     if snapshot_obj.vs_previous:
         click.echo("Delta vs. Previous:")
-        delta = snapshot_obj.vs_previous
+        delta = delta_from_dict(snapshot_obj.vs_previous) or SnapshotDelta()
         click.echo(f"  Nodes:       {delta.nodes:+d}")
         click.echo(f"  Edges:       {delta.edges:+d}")
         click.echo(f"  Coverage:    {delta.coverage_delta:+.1%}")
@@ -305,7 +312,7 @@ def show_snapshot(key: str, snapshots_dir: str | None) -> None:
 
     if snapshot_obj.vs_baseline:
         click.echo("Delta vs. Baseline:")
-        delta = snapshot_obj.vs_baseline
+        delta = delta_from_dict(snapshot_obj.vs_baseline) or SnapshotDelta()
         click.echo(f"  Nodes:       {delta.nodes:+d}")
         click.echo(f"  Edges:       {delta.edges:+d}")
         click.echo(f"  Coverage:    {delta.coverage_delta:+.1%}")

{pycode_kg-0.25.0 → pycode_kg-0.26.0}/src/pycode_kg/mcp_server.py

@@ -1653,7 +1653,7 @@ def snapshot_show(key: str = "latest") -> str:
     if snapshot is None:
         return json.dumps({"error": f"Snapshot not found for key: {key!r}"})
     out = snapshot.to_dict()
-    out["freshness"] = _snapshot_freshness(snapshot.metrics.total_nodes)
+    out["freshness"] = _snapshot_freshness(snapshot.metrics.get("total_nodes", 0))
     return json.dumps(out, indent=2, ensure_ascii=False)
 
 

{pycode_kg-0.25.0 → pycode_kg-0.26.0}/src/pycode_kg/pycodekg_thorough_analysis.py

@@ -333,12 +333,19 @@ def _has_property_decorator(source_lines: list[str], def_lineno: int) -> bool:
     found, matching ``@property``, ``@cached_property`` (bare or via
     ``functools``), and ``@<name>.setter/getter/deleter``.
 
+    ``def_lineno`` comes from the graph and ``source_lines`` from the file on
+    disk, so the two disagree whenever the graph is stale: a line number past
+    the end of the current file is normal after an edit, not a bug. Treat that
+    as "no property decorator" rather than indexing past the end -- a node
+    wrongly listed as an orphan is a report to re-read, an ``IndexError`` here
+    aborts the whole analysis phase.
+
     :param source_lines: Module source split into lines.
     :param def_lineno: 1-based line number of the ``def`` statement.
     :return: True when a property-family decorator precedes the definition.
     """
     i = def_lineno - 2  # 0-based index of the line above the def
-    while i >= 0:
+    while 0 <= i < len(source_lines):
         stripped = source_lines[i].strip()
         if not stripped.startswith("@"):
             break

pycode_kg-0.26.0/src/pycode_kg/snapshots.py

@@ -0,0 +1,357 @@
+"""
+snapshots.py — Temporal Snapshots of PyCodeKG Metrics
+
+Thin layer over the shared ``kg_utils.snapshots`` module.
+
+``Snapshot``, ``SnapshotManifest`` and ``PruneResult`` are re-exported from
+``kg_utils.snapshots`` unchanged.  A snapshot's ``metrics``, ``vs_previous``
+and ``vs_baseline`` are plain dicts, which is what the shared manager reads
+and writes.
+
+This module adds:
+
+  - ``SnapshotMetrics`` / ``SnapshotDelta`` — domain dataclasses, used as
+    converters by callers that want attribute access.  Convert with
+    ``metrics_from_dict`` / ``metrics_to_dict`` and ``delta_from_dict`` /
+    ``delta_to_dict``; a ``Snapshot`` never holds one.
+  - a ``SnapshotManager`` subclass that sets ``package_name="pycode-kg"``,
+    names the pycode-kg metric fields in ``capture()``, adds
+    ``coverage_delta`` and ``critical_issues_delta`` to deltas, collects
+    per-module node counts from SQLite, and extends a diff with
+    ``module_node_counts_delta``, ``issues_delta`` and ``timestamp``.
+
+Do not subclass ``Snapshot`` here.  A subclass that exposes ``metrics``,
+``vs_previous`` or ``vs_baseline`` as properties breaks every shared manager
+method that reads those fields by attribute, and each one then needs a
+hand-written copy.  One such copy dropped ``snapshot_key``, ``subject`` and
+``tool`` on the way to disk, which shipped in 0.25.0.
+
+Usage
+-----
+>>> from pycode_kg.snapshots import SnapshotManager, metrics_from_dict
+>>> mgr = SnapshotManager(".pycodekg/snapshots")
+>>> snapshot = mgr.capture(version="0.5.1", key="v0.5.1", subject="repo:pycode-kg")
+>>> mgr.save_snapshot(snapshot)
+>>> metrics_from_dict(snapshot.metrics).docstring_coverage
+0.0
+
+Author: Eric G. Suchanek, PhD
+
+License: Elastic 2.0
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Re-export shared base types (backwards-compat public API)
+# ---------------------------------------------------------------------------
+from kg_utils.snapshots import (
+    PruneResult,  # noqa: F401  re-exported
+    Snapshot,  # noqa: F401  re-exported
+    SnapshotManifest,  # noqa: F401  re-exported
+)
+from kg_utils.snapshots import SnapshotManager as _BaseSnapshotManager
+
+__all__ = [
+    "SnapshotMetrics",
+    "SnapshotDelta",
+    "Snapshot",
+    "SnapshotManifest",
+    "SnapshotManager",
+    "PruneResult",
+    "metrics_to_dict",
+    "metrics_from_dict",
+    "delta_to_dict",
+    "delta_from_dict",
+]
+
+
+# ---------------------------------------------------------------------------
+# Domain-specific dataclasses (used by CLI and tests)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SnapshotMetrics:
+    """Core metrics captured in a pycode-kg snapshot."""
+
+    total_nodes: int
+    total_edges: int
+    meaningful_nodes: int
+    docstring_coverage: float  # 0.0 to 1.0
+    node_counts: dict[str, int]
+    edge_counts: dict[str, int]
+    critical_issues: int
+    complexity_median: float  # median fan-in across functions
+    module_node_counts: dict[str, int] = field(default_factory=dict)
+    coverage_documented: int = 0  # nodes with a docstring
+    coverage_total: int = 0  # nodes eligible for docstring coverage
+
+
+@dataclass
+class SnapshotDelta:
+    """Deltas comparing this snapshot to a baseline or previous snapshot."""
+
+    nodes: int = 0
+    edges: int = 0
+    coverage_delta: float = 0.0
+    critical_issues_delta: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Conversion helpers
+# ---------------------------------------------------------------------------
+
+
+def metrics_to_dict(m: SnapshotMetrics) -> dict[str, Any]:
+    """Convert a ``SnapshotMetrics`` dataclass to a plain dict."""
+    return {
+        "total_nodes": m.total_nodes,
+        "total_edges": m.total_edges,
+        "meaningful_nodes": m.meaningful_nodes,
+        "docstring_coverage": m.docstring_coverage,
+        "node_counts": m.node_counts,
+        "edge_counts": m.edge_counts,
+        "critical_issues": m.critical_issues,
+        "complexity_median": m.complexity_median,
+        "module_node_counts": m.module_node_counts,
+        "coverage_documented": m.coverage_documented,
+        "coverage_total": m.coverage_total,
+    }
+
+
+def metrics_from_dict(d: dict[str, Any]) -> SnapshotMetrics:
+    """Reconstruct a ``SnapshotMetrics`` dataclass from a plain dict."""
+    return SnapshotMetrics(
+        total_nodes=int(d.get("total_nodes", 0)),
+        total_edges=int(d.get("total_edges", 0)),
+        meaningful_nodes=int(d.get("meaningful_nodes", 0)),
+        docstring_coverage=float(d.get("docstring_coverage", 0.0)),
+        node_counts=d.get("node_counts", {}),
+        edge_counts=d.get("edge_counts", {}),
+        critical_issues=int(d.get("critical_issues", 0)),
+        complexity_median=float(d.get("complexity_median", 0.0)),
+        module_node_counts=d.get("module_node_counts", {}),
+        coverage_documented=int(d.get("coverage_documented", 0)),
+        coverage_total=int(d.get("coverage_total", 0)),
+    )
+
+
+def delta_to_dict(delta: SnapshotDelta | None) -> dict[str, Any] | None:
+    """Convert a ``SnapshotDelta`` to a plain dict, or return None."""
+    if delta is None:
+        return None
+    return {
+        "nodes": delta.nodes,
+        "edges": delta.edges,
+        "coverage_delta": delta.coverage_delta,
+        "critical_issues_delta": delta.critical_issues_delta,
+    }
+
+
+def delta_from_dict(d: dict[str, Any] | None) -> SnapshotDelta | None:
+    """Reconstruct a ``SnapshotDelta`` from a plain dict, or return None."""
+    if d is None:
+        return None
+    return SnapshotDelta(
+        nodes=int(d.get("nodes", 0)),
+        edges=int(d.get("edges", 0)),
+        coverage_delta=float(d.get("coverage_delta", 0.0)),
+        critical_issues_delta=int(d.get("critical_issues_delta", 0)),
+    )
+
+
+# ---------------------------------------------------------------------------
+# SnapshotManager — pycode-kg specialisation of the shared manager
+# ---------------------------------------------------------------------------
+
+
+class SnapshotManager(_BaseSnapshotManager):
+    """pycode-kg snapshot manager.
+
+    Subclasses the shared ``kg_utils.snapshots.SnapshotManager`` and adds:
+
+    * ``package_name="pycode-kg"`` default for version detection.
+    * A ``capture()`` naming the pycode-kg metric fields (``coverage``,
+      ``critical_issues``, ``complexity_median`` and the coverage numerator
+      and denominator) and collecting per-module node counts.
+    * ``_compute_delta_from_metrics`` extended with ``coverage_delta`` and
+      ``critical_issues_delta``.
+    * ``diff_snapshots`` extended with ``module_node_counts_delta``,
+      ``issues_delta`` and ``timestamp``.
+    * ``_collect_module_node_counts()`` — SQLite per-module node counts.
+
+    Everything else -- saving, loading, listing, pruning, key handling -- is
+    inherited unchanged.  Overriding those to convert between dicts and the
+    domain dataclasses is what this module used to do, and is what let the
+    0.25.0 snapshot key regression through.
+    """
+
+    def __init__(
+        self,
+        snapshots_dir: Path | str,
+        *,
+        db_path: Path | str | None = None,
+        package_name: str = "pycode-kg",
+    ) -> None:
+        """Initialize the manager rooted at ``snapshots_dir``.
+
+        :param snapshots_dir: Directory where snapshot JSON files live; created
+            on first save if it does not exist.
+        :param db_path: PyCodeKG SQLite graph path; required for collecting
+            per-module node counts during ``capture()``. Optional otherwise.
+        :param package_name: Package name used for version detection in saved
+            snapshots. Defaults to ``"pycode-kg"``.
+        """
+        super().__init__(snapshots_dir, package_name=package_name, db_path=db_path)
+
+    # ------------------------------------------------------------------
+    # capture — name the pycode-kg metric fields
+    # ------------------------------------------------------------------
+
+    def capture(  # ty: ignore[invalid-method-override]
+        self,
+        version: str | None = None,
+        branch: str | None = None,
+        graph_stats_dict: dict[str, Any] | None = None,
+        coverage: float = 0.0,
+        coverage_documented: int = 0,
+        coverage_total: int = 0,
+        critical_issues: int = 0,
+        complexity_median: float = 0.0,
+        hotspots: list[dict[str, Any]] | None = None,
+        issues: list[str] | None = None,
+        tree_hash: str = "",
+        key: str = "",
+        subject: str = "",
+    ) -> Snapshot:
+        """Capture a pycode-kg snapshot.
+
+        Names the pycode-kg metric fields explicitly rather than taking them
+        through ``**extra_metrics``, and adds per-module node counts, then
+        delegates to the shared implementation.
+
+        :param version: Version string (e.g., "0.5.1").
+        :param branch: Git branch name; auto-detected if None.
+        :param graph_stats_dict: Output from ``graph_stats()`` / ``store.stats()``.
+        :param coverage: Docstring coverage fraction (0.0-1.0).
+        :param coverage_documented: Nodes with a non-empty docstring — the
+            numerator behind ``coverage``.  Shown beside the percentage in
+            Snapshot History so a coverage drop caused by adding undocumented
+            nodes reads differently from one caused by removing docstrings.
+        :param coverage_total: Nodes eligible for docstring coverage — the
+            denominator behind ``coverage``.
+        :param critical_issues: Number of critical issues detected.
+        :param complexity_median: Median fan-in across functions.
+        :param hotspots: Top hotspot entries.
+        :param issues: Issue description strings.
+        :param tree_hash: Git tree hash, recorded as provenance; auto-detected
+            if not provided. It is not the snapshot's key.
+        :param key: Snapshot identifier. Pass the release tag at release time;
+            omit it and the base assigns a UTC timestamp.
+        :param subject: What was measured, e.g. ``repo:pycode-kg``.
+        :return: New :class:`~kg_utils.snapshots.Snapshot` (not yet persisted).
+        """
+        return super().capture(
+            version=version,
+            branch=branch,
+            graph_stats_dict=graph_stats_dict,
+            tree_hash=tree_hash,
+            key=key,
+            subject=subject,
+            hotspots=hotspots,
+            issues=issues,
+            docstring_coverage=coverage,
+            coverage_documented=coverage_documented,
+            coverage_total=coverage_total,
+            critical_issues=critical_issues,
+            complexity_median=complexity_median,
+            module_node_counts=self._collect_module_node_counts(),
+        )
+
+    # ------------------------------------------------------------------
+    # diff_snapshots — adds module_node_counts_delta, issues_delta, timestamp
+    # ------------------------------------------------------------------
+
+    def diff_snapshots(self, key_a: str, key_b: str) -> dict[str, Any]:
+        """Compare two snapshots side-by-side.
+
+        Extends the shared diff with ``module_node_counts_delta``,
+        ``issues_delta`` (introduced / resolved issue strings) and the
+        ``timestamp`` of each side, which the CLI prints.
+
+        :param key_a: Earlier snapshot key.
+        :param key_b: Later snapshot key.
+        :return: The shared diff result with the pycode-kg additions.
+        """
+        result = super().diff_snapshots(key_a, key_b)
+        if "error" in result:
+            return result
+
+        for side, key in (("a", key_a), ("b", key_b)):
+            snap = self.load_snapshot(key)
+            if snap is not None:
+                result[side]["timestamp"] = snap.timestamp
+
+        m_a: dict[str, Any] = result["a"]["metrics"]
+        m_b: dict[str, Any] = result["b"]["metrics"]
+        counts_a: dict[str, int] = m_a.get("module_node_counts", {})
+        counts_b: dict[str, int] = m_b.get("module_node_counts", {})
+        result["module_node_counts_delta"] = {
+            mod: counts_b.get(mod, 0) - counts_a.get(mod, 0)
+            for mod in set(counts_a) | set(counts_b)
+            if counts_b.get(mod, 0) != counts_a.get(mod, 0)
+        }
+
+        issues_a = set(result["a"]["issues"])
+        issues_b = set(result["b"]["issues"])
+        result["issues_delta"] = {
+            "introduced": list(issues_b - issues_a),
+            "resolved": list(issues_a - issues_b),
+        }
+        return result
+
+    # ------------------------------------------------------------------
+    # Delta computation — adds coverage_delta and critical_issues_delta
+    # ------------------------------------------------------------------
+
+    def _compute_delta_from_metrics(
+        self, new_m: dict[str, Any], old_m: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Compute delta dict including pycode-kg specific fields."""
+        return {
+            "nodes": new_m.get("total_nodes", 0) - old_m.get("total_nodes", 0),
+            "edges": new_m.get("total_edges", 0) - old_m.get("total_edges", 0),
+            "coverage_delta": (
+                new_m.get("docstring_coverage", 0.0) - old_m.get("docstring_coverage", 0.0)
+            ),
+            "critical_issues_delta": (
+                new_m.get("critical_issues", 0) - old_m.get("critical_issues", 0)
+            ),
+        }
+
+    # ------------------------------------------------------------------
+    # SQLite per-module node counts
+    # ------------------------------------------------------------------
+
+    def _collect_module_node_counts(self) -> dict[str, int]:
+        """Query SQLite for per-module node counts.
+
+        :return: Dict mapping ``module_path`` to node count, or ``{}`` if the
+                 database is unavailable or the query fails.
+        """
+        if not self.db_path or not self.db_path.exists():
+            return {}
+        try:
+            with sqlite3.connect(self.db_path) as conn:
+                rows = conn.execute(
+                    "SELECT module_path, COUNT(*) FROM nodes GROUP BY module_path"
+                ).fetchall()
+            return {row[0]: row[1] for row in rows if row[0]}
+        except sqlite3.Error:
+            return {}

pycode_kg-0.25.0/src/pycode_kg/snapshots.py

@@ -1,531 +0,0 @@
-"""
-snapshots.py — Temporal Snapshots of PyCodeKG Metrics
-
-Thin compatibility layer over the shared ``kg_utils.snapshots`` module.
-
-The shared module provides canonical ``Snapshot``, ``SnapshotManifest``, and
-``SnapshotManager`` backed by free-form dicts.  This module re-exports those
-types and adds:
-
-  - ``SnapshotMetrics`` — domain-specific dataclass (used by CLI and tests)
-  - ``SnapshotDelta``   — domain-specific dataclass (used by CLI and tests)
-  - ``SnapshotManager`` subclass that:
-      * sets ``package_name="pycode-kg"`` by default
-      * overrides ``capture()`` to accept the legacy per-field kwargs
-        (``coverage``, ``critical_issues``, ``complexity_median``) and
-        build the structured ``metrics`` dict
-      * overrides ``_compute_delta_from_metrics`` to include
-        ``coverage_delta`` and ``critical_issues_delta``
-      * adds ``_collect_module_node_counts()`` — SQLite per-module counts
-  - ``metrics_to_dict`` / ``metrics_from_dict`` — helpers for converting
-    between ``SnapshotMetrics`` dataclass and the underlying dict
-  - ``delta_to_dict`` / ``delta_from_dict`` — same for ``SnapshotDelta``
-
-``Snapshot`` is re-exported from ``kg_utils.snapshots``.  For backwards
-compatibility ``snapshot.metrics`` returns a ``SnapshotMetrics``-shaped
-view object when the snapshot was constructed via this module's helpers.
-
-Usage
------
->>> from pycode_kg.snapshots import SnapshotManager
->>> mgr = SnapshotManager(".pycodekg/snapshots")
->>> snapshot = mgr.capture("v0.5.1", "develop", graph_stats_dict)
->>> mgr.save_snapshot(snapshot)
->>> manifest = mgr.load_manifest()
->>> prev = mgr.get_previous(tree_hash)
-
-Author: Eric G. Suchanek, PhD
-
-License: Elastic 2.0
-"""
-
-from __future__ import annotations
-
-import sqlite3
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any
-
-# ---------------------------------------------------------------------------
-# Re-export shared base types (backwards-compat public API)
-# ---------------------------------------------------------------------------
-from kg_utils.snapshots import (
-    PruneResult,  # noqa: F401  re-exported
-    SnapshotManifest,  # noqa: F401  re-exported
-)
-from kg_utils.snapshots import Snapshot as _BaseSnapshot
-from kg_utils.snapshots import SnapshotManager as _BaseSnapshotManager
-
-__all__ = [
-    "SnapshotMetrics",
-    "SnapshotDelta",
-    "Snapshot",
-    "SnapshotManifest",
-    "SnapshotManager",
-    "PruneResult",
-    "metrics_to_dict",
-    "metrics_from_dict",
-    "delta_to_dict",
-    "delta_from_dict",
-]
-
-
-# ---------------------------------------------------------------------------
-# Domain-specific dataclasses (used by CLI and tests)
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class SnapshotMetrics:
-    """Core metrics captured in a pycode-kg snapshot."""
-
-    total_nodes: int
-    total_edges: int
-    meaningful_nodes: int
-    docstring_coverage: float  # 0.0 to 1.0
-    node_counts: dict[str, int]
-    edge_counts: dict[str, int]
-    critical_issues: int
-    complexity_median: float  # median fan-in across functions
-    module_node_counts: dict[str, int] = field(default_factory=dict)
-    coverage_documented: int = 0  # nodes with a docstring
-    coverage_total: int = 0  # nodes eligible for docstring coverage
-
-
-@dataclass
-class SnapshotDelta:
-    """Deltas comparing this snapshot to a baseline or previous snapshot."""
-
-    nodes: int = 0
-    edges: int = 0
-    coverage_delta: float = 0.0
-    critical_issues_delta: int = 0
-
-
-# ---------------------------------------------------------------------------
-# Conversion helpers
-# ---------------------------------------------------------------------------
-
-
-def metrics_to_dict(m: SnapshotMetrics) -> dict[str, Any]:
-    """Convert a ``SnapshotMetrics`` dataclass to a plain dict."""
-    return {
-        "total_nodes": m.total_nodes,
-        "total_edges": m.total_edges,
-        "meaningful_nodes": m.meaningful_nodes,
-        "docstring_coverage": m.docstring_coverage,
-        "node_counts": m.node_counts,
-        "edge_counts": m.edge_counts,
-        "critical_issues": m.critical_issues,
-        "complexity_median": m.complexity_median,
-        "module_node_counts": m.module_node_counts,
-        "coverage_documented": m.coverage_documented,
-        "coverage_total": m.coverage_total,
-    }
-
-
-def metrics_from_dict(d: dict[str, Any]) -> SnapshotMetrics:
-    """Reconstruct a ``SnapshotMetrics`` dataclass from a plain dict."""
-    return SnapshotMetrics(
-        total_nodes=int(d.get("total_nodes", 0)),
-        total_edges=int(d.get("total_edges", 0)),
-        meaningful_nodes=int(d.get("meaningful_nodes", 0)),
-        docstring_coverage=float(d.get("docstring_coverage", 0.0)),
-        node_counts=d.get("node_counts", {}),
-        edge_counts=d.get("edge_counts", {}),
-        critical_issues=int(d.get("critical_issues", 0)),
-        complexity_median=float(d.get("complexity_median", 0.0)),
-        module_node_counts=d.get("module_node_counts", {}),
-        coverage_documented=int(d.get("coverage_documented", 0)),
-        coverage_total=int(d.get("coverage_total", 0)),
-    )
-
-
-def delta_to_dict(delta: SnapshotDelta | None) -> dict[str, Any] | None:
-    """Convert a ``SnapshotDelta`` to a plain dict, or return None."""
-    if delta is None:
-        return None
-    return {
-        "nodes": delta.nodes,
-        "edges": delta.edges,
-        "coverage_delta": delta.coverage_delta,
-        "critical_issues_delta": delta.critical_issues_delta,
-    }
-
-
-def delta_from_dict(d: dict[str, Any] | None) -> SnapshotDelta | None:
-    """Reconstruct a ``SnapshotDelta`` from a plain dict, or return None."""
-    if d is None:
-        return None
-    return SnapshotDelta(
-        nodes=int(d.get("nodes", 0)),
-        edges=int(d.get("edges", 0)),
-        coverage_delta=float(d.get("coverage_delta", 0.0)),
-        critical_issues_delta=int(d.get("critical_issues_delta", 0)),
-    )
-
-
-# ---------------------------------------------------------------------------
-# Snapshot — thin compatibility wrapper around the shared dict-based model
-# ---------------------------------------------------------------------------
-
-
-class Snapshot(_BaseSnapshot):
-    """pycode-kg Snapshot with attribute-style access to metrics and deltas.
-
-    Extends the shared ``kg_utils.snapshots.Snapshot`` (which stores metrics
-    as a free-form dict) with ``@property`` accessors that return the typed
-    ``SnapshotMetrics`` and ``SnapshotDelta`` objects that the CLI and tests
-    expect.
-
-    The underlying ``metrics``, ``vs_previous``, and ``vs_baseline`` fields
-    remain plain dicts on disk; the properties are view-only adapters.
-
-    ``to_dict`` is **not** overridden. The base reads those three fields out of
-    ``__dict__`` rather than through these properties (kgmodule-utils 0.19.0),
-    which is what the override used to exist for -- and the base is also what
-    supplies the current key scheme, so an override here would silently keep
-    writing tree-hash keys.
-
-    Implementation note
-    -------------------
-    Python dataclass fields are stored in ``__dict__`` under their field name.
-    The properties below always read and write the raw dict stored in
-    ``self.__dict__`` directly so that the shared base-class infrastructure
-    (which expects plain dicts) continues to work without modification.
-    """
-
-    @property  # type: ignore[override]
-    def metrics(self) -> SnapshotMetrics:  # type: ignore[override]
-        """Return metrics as a ``SnapshotMetrics`` dataclass view."""
-        return metrics_from_dict(self.__dict__["metrics"])
-
-    @metrics.setter
-    def metrics(self, value: SnapshotMetrics | dict[str, Any]) -> None:
-        if isinstance(value, SnapshotMetrics):
-            self.__dict__["metrics"] = metrics_to_dict(value)
-        else:
-            self.__dict__["metrics"] = value
-
-    @property  # type: ignore[override]
-    def vs_previous(self) -> SnapshotDelta | None:  # type: ignore[override]
-        """Return vs_previous as a ``SnapshotDelta`` dataclass view."""
-        return delta_from_dict(self.__dict__["vs_previous"])
-
-    @vs_previous.setter
-    def vs_previous(self, value: SnapshotDelta | dict[str, Any] | None) -> None:
-        if isinstance(value, SnapshotDelta):
-            self.__dict__["vs_previous"] = delta_to_dict(value)
-        else:
-            self.__dict__["vs_previous"] = value
-
-    @property  # type: ignore[override]
-    def vs_baseline(self) -> SnapshotDelta | None:  # type: ignore[override]
-        """Return vs_baseline as a ``SnapshotDelta`` dataclass view."""
-        return delta_from_dict(self.__dict__["vs_baseline"])
-
-    @vs_baseline.setter
-    def vs_baseline(self, value: SnapshotDelta | dict[str, Any] | None) -> None:
-        if isinstance(value, SnapshotDelta):
-            self.__dict__["vs_baseline"] = delta_to_dict(value)
-        else:
-            self.__dict__["vs_baseline"] = value
-
-    @staticmethod
-    def from_dict(data: dict[str, Any]) -> Snapshot:  # type: ignore[override]
-        """Reconstruct a pycode-kg ``Snapshot`` from a dictionary."""
-        base = _BaseSnapshot.from_dict(data)
-        return _rewrap(base)
-
-
-# ---------------------------------------------------------------------------
-# SnapshotManager — pycode-kg specialisation of the shared manager
-# ---------------------------------------------------------------------------
-
-
-class SnapshotManager(_BaseSnapshotManager):
-    """pycode-kg snapshot manager.
-
-    Subclasses the shared ``kg_utils.snapshots.SnapshotManager`` and adds:
-
-    * ``package_name="pycode-kg"`` default for version detection.
-    * Legacy ``capture()`` kwargs: ``coverage``, ``critical_issues``,
-      ``complexity_median`` — merged into the metrics dict.
-    * ``_compute_delta_from_metrics`` extended with ``coverage_delta`` and
-      ``critical_issues_delta``.
-    * ``_collect_module_node_counts()`` — SQLite per-module node counts stored
-      in snapshot metrics under ``"module_node_counts"``.
-    * Returns ``pycode_kg.snapshots.Snapshot`` instances (with typed-accessor
-      properties) from all load/capture methods.
-    """
-
-    def __init__(
-        self,
-        snapshots_dir: Path | str,
-        *,
-        db_path: Path | str | None = None,
-        package_name: str = "pycode-kg",
-    ) -> None:
-        """Initialize the manager rooted at ``snapshots_dir``.
-
-        :param snapshots_dir: Directory where snapshot JSON files live; created
-            on first save if it does not exist.
-        :param db_path: PyCodeKG SQLite graph path; required for collecting
-            per-module node counts during ``capture()``. Optional otherwise.
-        :param package_name: Package name used for version detection in saved
-            snapshots. Defaults to ``"pycode-kg"``.
-        """
-        super().__init__(snapshots_dir, package_name=package_name, db_path=db_path)
-
-    # ------------------------------------------------------------------
-    # capture — backwards-compat wrapper
-    # ------------------------------------------------------------------
-
-    def capture(  # ty: ignore[invalid-method-override]
-        self,
-        version: str | None = None,
-        branch: str | None = None,
-        graph_stats_dict: dict[str, Any] | None = None,
-        coverage: float = 0.0,
-        coverage_documented: int = 0,
-        coverage_total: int = 0,
-        critical_issues: int = 0,
-        complexity_median: float = 0.0,
-        hotspots: list[dict[str, Any]] | None = None,
-        issues: list[str] | None = None,
-        tree_hash: str = "",
-        key: str = "",
-        subject: str = "",
-    ) -> Snapshot:
-        """Capture a pycode-kg snapshot.
-
-        Accepts the legacy per-field kwargs (``coverage``, ``critical_issues``,
-        ``complexity_median``) in addition to the dict-based
-        ``graph_stats_dict`` from the base class, and builds the full metrics
-        dict expected by the shared infrastructure.
-
-        :param version: Version string (e.g., "0.5.1").
-        :param branch: Git branch name; auto-detected if None.
-        :param graph_stats_dict: Output from ``graph_stats()`` / ``store.stats()``.
-        :param coverage: Docstring coverage fraction (0.0–1.0).
-        :param coverage_documented: Nodes with a non-empty docstring — the
-            numerator behind ``coverage``.  Shown beside the percentage in
-            Snapshot History so a coverage drop caused by adding undocumented
-            nodes reads differently from one caused by removing docstrings.
-        :param coverage_total: Nodes eligible for docstring coverage — the
-            denominator behind ``coverage``.
-        :param critical_issues: Number of critical issues detected.
-        :param complexity_median: Median fan-in across functions.
-        :param hotspots: Top hotspot entries.
-        :param issues: Issue description strings.
-        :param tree_hash: Git tree hash, recorded as provenance; auto-detected
-            if not provided. It is not the snapshot's key.
-        :param key: Snapshot identifier. Pass the release tag at release time;
-            omit it and the base assigns a UTC timestamp.
-        :param subject: What was measured, e.g. ``repo:pycode-kg``.
-        :return: New :class:`Snapshot` instance (not yet persisted).
-        """
-        module_node_counts = self._collect_module_node_counts()
-
-        base_snap = super().capture(
-            version=version,
-            branch=branch,
-            graph_stats_dict=graph_stats_dict,
-            tree_hash=tree_hash,
-            key=key,
-            subject=subject,
-            hotspots=hotspots,
-            issues=issues,
-            docstring_coverage=coverage,
-            coverage_documented=coverage_documented,
-            coverage_total=coverage_total,
-            critical_issues=critical_issues,
-            complexity_median=complexity_median,
-            module_node_counts=module_node_counts,
-        )
-
-        return _rewrap(base_snap)
-
-    # ------------------------------------------------------------------
-    # diff_snapshots — adds module_node_counts_delta and issues_delta
-    # ------------------------------------------------------------------
-
-    def diff_snapshots(self, key_a: str, key_b: str) -> dict[str, Any]:
-        """Compare two snapshots side-by-side.
-
-        Extends the base diff with ``module_node_counts_delta`` and
-        ``issues_delta`` (introduced / resolved issue strings).
-
-        :param key_a: First snapshot key (tree hash).
-        :param key_b: Second snapshot key (tree hash).
-        :return: Dict with metrics from both, computed deltas.
-        """
-        snap_a = _BaseSnapshotManager.load_snapshot(self, key_a)
-        snap_b = _BaseSnapshotManager.load_snapshot(self, key_b)
-
-        if not snap_a or not snap_b:
-            return {"error": "One or both snapshots not found"}
-
-        m_a = snap_a.metrics
-        m_b = snap_b.metrics
-
-        all_node_kinds = set(m_a.get("node_counts", {})) | set(m_b.get("node_counts", {}))
-        all_edge_rels = set(m_a.get("edge_counts", {})) | set(m_b.get("edge_counts", {}))
-
-        node_counts_delta = {
-            k: m_b.get("node_counts", {}).get(k, 0) - m_a.get("node_counts", {}).get(k, 0)
-            for k in all_node_kinds
-        }
-        edge_counts_delta = {
-            k: m_b.get("edge_counts", {}).get(k, 0) - m_a.get("edge_counts", {}).get(k, 0)
-            for k in all_edge_rels
-        }
-
-        all_modules = set(m_a.get("module_node_counts", {})) | set(
-            m_b.get("module_node_counts", {})
-        )
-        module_node_counts_delta = {
-            mod: m_b.get("module_node_counts", {}).get(mod, 0)
-            - m_a.get("module_node_counts", {}).get(mod, 0)
-            for mod in all_modules
-            if m_b.get("module_node_counts", {}).get(mod, 0)
-            != m_a.get("module_node_counts", {}).get(mod, 0)
-        }
-
-        issues_a = set(snap_a.issues)
-        issues_b = set(snap_b.issues)
-
-        return {
-            "a": {
-                "key": snap_a.key,
-                "metrics": m_a,
-                "issues": snap_a.issues,
-                "timestamp": snap_a.timestamp,
-            },
-            "b": {
-                "key": snap_b.key,
-                "metrics": m_b,
-                "issues": snap_b.issues,
-                "timestamp": snap_b.timestamp,
-            },
-            "delta": self._compute_delta_from_metrics(m_b, m_a),
-            "node_counts_delta": node_counts_delta,
-            "edge_counts_delta": edge_counts_delta,
-            "module_node_counts_delta": module_node_counts_delta,
-            "issues_delta": {
-                "introduced": list(issues_b - issues_a),
-                "resolved": list(issues_a - issues_b),
-            },
-        }
-
-    # ------------------------------------------------------------------
-    # Delta computation — adds coverage_delta and critical_issues_delta
-    # ------------------------------------------------------------------
-
-    def _compute_delta(self, snap_new: _BaseSnapshot, snap_old: _BaseSnapshot) -> dict[str, Any]:
-        """Compute delta, extracting raw metric dicts to avoid the typed-property layer."""
-        new_m = snap_new.__dict__.get("metrics", snap_new.metrics)
-        old_m = snap_old.__dict__.get("metrics", snap_old.metrics)
-        if isinstance(new_m, SnapshotMetrics):
-            new_m = metrics_to_dict(new_m)
-        if isinstance(old_m, SnapshotMetrics):
-            old_m = metrics_to_dict(old_m)
-        return self._compute_delta_from_metrics(new_m, old_m)
-
-    def _compute_delta_from_metrics(
-        self, new_m: dict[str, Any], old_m: dict[str, Any]
-    ) -> dict[str, Any]:
-        """Compute delta dict including pycode-kg specific fields."""
-        return {
-            "nodes": new_m.get("total_nodes", 0) - old_m.get("total_nodes", 0),
-            "edges": new_m.get("total_edges", 0) - old_m.get("total_edges", 0),
-            "coverage_delta": (
-                new_m.get("docstring_coverage", 0.0) - old_m.get("docstring_coverage", 0.0)
-            ),
-            "critical_issues_delta": (
-                new_m.get("critical_issues", 0) - old_m.get("critical_issues", 0)
-            ),
-        }
-
-    # ------------------------------------------------------------------
-    # save_snapshot — normalise typed properties back to raw dicts first
-    # ------------------------------------------------------------------
-
-    def save_snapshot(self, snapshot: _BaseSnapshot, *, force: bool = False) -> Any:
-        """Persist snapshot, normalising any typed-property values to raw dicts.
-
-        The base ``save_snapshot`` inspects ``snapshot.metrics`` (expects a
-        dict) and ``snapshot.vs_previous`` / ``snapshot.vs_baseline`` (expects
-        dicts or None) directly.  If ``snapshot`` is a pycode-kg ``Snapshot``
-        the properties return typed dataclasses instead; we substitute a plain
-        ``_BaseSnapshot`` carrying the raw dicts so the base implementation
-        can serialise without modification.
-        """
-        if isinstance(snapshot, Snapshot):
-            raw = _BaseSnapshot(
-                branch=snapshot.branch,
-                timestamp=snapshot.timestamp,
-                version=snapshot.version,
-                metrics=snapshot.__dict__["metrics"],
-                hotspots=snapshot.hotspots,
-                issues=snapshot.issues,
-                vs_previous=snapshot.__dict__["vs_previous"],
-                vs_baseline=snapshot.__dict__["vs_baseline"],
-                tree_hash=snapshot.tree_hash,
-            )
-            return super().save_snapshot(raw, force=force)
-        return super().save_snapshot(snapshot, force=force)
-
-    # ------------------------------------------------------------------
-    # Load helpers — re-wrap base Snapshot instances as pycode-kg Snapshots
-    # ------------------------------------------------------------------
-
-    def load_snapshot(self, key: str) -> Snapshot | None:  # type: ignore[override]
-        """Load a snapshot by key and re-wrap it as a pycode-kg ``Snapshot`` with typed-accessor properties. Returns ``None`` if no snapshot matches."""
-        snap = super().load_snapshot(key)
-        return _rewrap(snap) if snap is not None else None
-
-    def get_previous(self, key: str) -> Snapshot | None:  # type: ignore[override]
-        """Return the snapshot immediately preceding ``key`` in manifest chronology, re-wrapped as a pycode-kg ``Snapshot``. ``None`` when ``key`` is the earliest."""
-        snap = super().get_previous(key)
-        return _rewrap(snap) if snap is not None else None
-
-    def get_baseline(self) -> Snapshot | None:  # type: ignore[override]
-        """Return the earliest (baseline) snapshot in the manifest, re-wrapped as a pycode-kg ``Snapshot``. ``None`` if no snapshots exist."""
-        snap = super().get_baseline()
-        return _rewrap(snap) if snap is not None else None
-
-    # ------------------------------------------------------------------
-    # SQLite per-module node counts
-    # ------------------------------------------------------------------
-
-    def _collect_module_node_counts(self) -> dict[str, int]:
-        """Query SQLite for per-module node counts.
-
-        :return: Dict mapping ``module_path`` to node count, or ``{}`` if the
-                 database is unavailable or the query fails.
-        """
-        if not self.db_path or not self.db_path.exists():
-            return {}
-        try:
-            with sqlite3.connect(self.db_path) as conn:
-                rows = conn.execute(
-                    "SELECT module_path, COUNT(*) FROM nodes GROUP BY module_path"
-                ).fetchall()
-            return {row[0]: row[1] for row in rows if row[0]}
-        except sqlite3.Error:
-            return {}
-
-
-# ---------------------------------------------------------------------------
-# Internal helper
-# ---------------------------------------------------------------------------
-
-
-def _rewrap(base: _BaseSnapshot) -> Snapshot:
-    """Re-wrap a base Snapshot as a pycode-kg Snapshot (no data copying)."""
-    if isinstance(base, Snapshot):
-        return base
-    snap = Snapshot.__new__(Snapshot)
-    snap.__dict__.update(base.__dict__)
-    return snap