pycode-kg 0.25.1__tar.gz → 0.27.0__tar.gz

{pycode_kg-0.25.1 → pycode_kg-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.25.1
+Version: 0.27.0
 Summary: A tool to build a searchable knowledge graph from Python repositories
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -21,8 +21,8 @@ Provides-Extra: viz3d
 Requires-Dist: PyQt5 (>=5.15.0) ; extra == "all"
 Requires-Dist: PyQt5 (>=5.15.0) ; extra == "viz3d"
 Requires-Dist: click (>=8.1.0,<9)
-Requires-Dist: kgmodule-utils[semantic,viz3d] (>=0.19.0)
-Requires-Dist: kgmodule-utils[viz3d-qt,viz3d-render] (>=0.18.1) ; extra == "viz3d"
+Requires-Dist: kgmodule-utils[semantic,viz3d] (>=0.20.0)
+Requires-Dist: kgmodule-utils[viz3d-qt,viz3d-render] (>=0.20.0) ; extra == "viz3d"
 Requires-Dist: markdown (>=3.6) ; extra == "all"
 Requires-Dist: markdown (>=3.6) ; extra == "viz3d"
 Requires-Dist: mcp (>=1.0.0,<2)
@@ -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.1-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.27.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.1.md](docs/analysis_v0.25.1.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.27.0.md](docs/analysis_v0.27.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.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.27.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.1},
+  version   = {0.27.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

{pycode_kg-0.25.1 → pycode_kg-0.27.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.1-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.27.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.1.md](docs/analysis_v0.25.1.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.27.0.md](docs/analysis_v0.27.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.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.27.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.1},
+  version   = {0.27.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

{pycode_kg-0.25.1 → pycode_kg-0.27.0}/pyproject.toml

@@ -70,7 +70,7 @@ torch = [
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.25.1"
+version = "0.27.0"
 description = "A tool to build a searchable knowledge graph from Python repositories"
 readme = "README.md"
 license = "Elastic-2.0"
@@ -155,7 +155,21 @@ dependencies = [
     # this repo's visitor writes as of 0.24.1 -- against 0.18.0 the stubs are
     # tagged correctly but the tag is silently ignored, so resolution stays on
     # the old untyped trailing-name match with no error to say so.
-    "kgmodule-utils[semantic,viz3d]>=0.19.0",
+    #
+    # 0.19.1 because SnapshotManager.load_snapshot back-fills a missing
+    # vs_previous through _compute_delta_from_metrics as of that release.
+    # Against 0.19.0 the backfill uses a hardcoded nodes/edges dict, so
+    # coverage_delta and critical_issues_delta read as zero in `snapshot show`
+    # for every snapshot whose deltas were not persisted at capture -- which is
+    # the normal path, not a legacy one.
+    #
+    # 0.20.0 is a hard requirement, not a preference: snapshots.py has no
+    # __init__, capture or diff_snapshots of its own any more. It configures
+    # the base through the package_name and dict_metric_deltas class attributes
+    # and the _domain_metrics() hook, none of which exist before 0.20.0.
+    # Against 0.19.x the manager silently reports itself as "kg-utils" and
+    # drops module_node_counts entirely.
+    "kgmodule-utils[semantic,viz3d]>=0.20.0",
 ]
 
 [project.optional-dependencies]
@@ -180,7 +194,7 @@ viz3d = [
     # the four-step build/render/write/cast itself. It subsumes [viz3d-render]
     # (it declares pyvista too), but both are named so the dependency reads as
     # what it is rather than as a side effect.
-    "kgmodule-utils[viz3d-render,viz3d-qt]>=0.18.1",
+    "kgmodule-utils[viz3d-render,viz3d-qt]>=0.20.0",
     "pyvistaqt>=0.11.0",
     "trame-vtk>=2.0.0",
     # Looking Glass quilts. 0.4.0 supplies depth_report() and widened

{pycode_kg-0.25.1 → pycode_kg-0.27.0}/src/pycode_kg/__init__.py

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

{pycode_kg-0.25.1 → pycode_kg-0.27.0}/src/pycode_kg/cli/cmd_init.py

@@ -277,7 +277,7 @@ def init(
                 version=version,
                 branch=branch,
                 graph_stats_dict=stats,
-                coverage=coverage,
+                docstring_coverage=coverage,
                 coverage_documented=coverage_documented,
                 coverage_total=coverage_total,
                 critical_issues=critical_issues,

{pycode_kg-0.25.1 → pycode_kg-0.27.0}/src/pycode_kg/cli/cmd_snapshot.py

@@ -19,16 +19,49 @@ import json
 from pathlib import Path
 
 import click
+from click.core import ParameterSource
 
 from pycode_kg.cli.main import cli
 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
 
 
+def _graph_for_repo(sqlite: str, repo_root: Path) -> Path:
+    """Resolve the graph path, anchoring the default to ``--repo``.
+
+    ``--sqlite`` defaults to the relative ``.pycodekg/graph.sqlite``, which
+    click resolves against the *current working directory*, while
+    ``--repo`` decides where the snapshot is filed. Left alone, the two
+    disagree: ``pycodekg snapshot save 1.0.0 --repo /other/project`` run from
+    inside this repo reads *this* repo's graph and writes the result into
+    */other/project*'s snapshots directory -- a snapshot whose metrics belong
+    to one project and whose provenance claims another, with no error.
+
+    An explicitly passed ``--sqlite`` is always honoured as given; only the
+    default is re-anchored. The other commands sharing ``sqlite_option``
+    (``query``, ``explain``) take no ``--repo``, so cwd is the right base for
+    them and they are unaffected.
+
+    :param sqlite: The ``--sqlite`` value, explicit or default.
+    :param repo_root: The resolved ``--repo`` path.
+    :return: The graph database path to read.
+    """
+    ctx = click.get_current_context(silent=True)
+    source = ctx.get_parameter_source("sqlite") if ctx is not None else None
+    if source is not None and source is not ParameterSource.DEFAULT:
+        return Path(sqlite)
+    return repo_root / ".pycodekg" / "graph.sqlite"
+
+
 @cli.group("snapshot")
 def snapshot() -> None:
     """Manage temporal snapshots of PyCodeKG metrics."""
@@ -100,7 +133,7 @@ def save_snapshot(
         pycodekg snapshot save 0.5.1 --repo .
     """
     repo_root = Path(repo).resolve()
-    db_path = Path(sqlite)
+    db_path = _graph_for_repo(sqlite, repo_root)
     snapshots_path = (
         Path(snapshots_dir).resolve() if snapshots_dir else (repo_root / ".pycodekg" / "snapshots")
     )
@@ -156,7 +189,7 @@ def save_snapshot(
         version=version,
         branch=branch,
         graph_stats_dict=stats,
-        coverage=coverage,
+        docstring_coverage=coverage,
         coverage_documented=coverage_documented,
         coverage_total=coverage_total,
         critical_issues=critical_issues,
@@ -174,9 +207,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 +304,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 +331,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 +340,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.1 → pycode_kg-0.27.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.1 → pycode_kg-0.27.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.27.0/src/pycode_kg/snapshots.py

@@ -0,0 +1,273 @@
+"""
+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"``,
+    collects the pycode-kg metric fields in ``_domain_metrics()``, 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 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``. Three of the
+    four additions are class attributes rather than methods, because the base
+    supplies the behaviour and this module only names the domain values:
+
+    * ``package_name = "pycode-kg"`` for version detection.
+    * ``dict_metric_deltas`` naming ``module_node_counts``, which the base
+      turns into ``module_node_counts_delta`` in ``diff_snapshots``.
+    * ``_domain_metrics()`` collecting per-module node counts at capture time.
+    * ``_compute_delta_from_metrics`` extended with ``coverage_delta`` and
+      ``critical_issues_delta`` — the one genuinely domain-specific method.
+    * ``_collect_module_node_counts()`` — SQLite per-module node counts.
+
+    Everything else -- capture, saving, loading, listing, pruning, diffing, key
+    handling -- is inherited unchanged. Overriding those is what this module
+    used to do, and is what let the 0.25.0 snapshot key regression through.
+
+    Note that ``capture()`` takes the coverage fraction as
+    ``docstring_coverage``, the name it is stored under. Until 0.27.0 this
+    class overrode ``capture()`` to accept it as ``coverage`` and rename it on
+    the way through; that override is gone, and with it the signature-restating
+    pattern that let a ``key=`` go missing. ``coverage=`` still works and warns
+    -- see ``capture_aliases`` below.
+    """
+
+    #: Version detection reads this; the base uses it as the snapshot's ``tool``.
+    package_name = "pycode-kg"
+
+    #: ``diff_snapshots`` emits ``module_node_counts_delta`` from this, holding
+    #: only the modules whose node count actually changed.
+    dict_metric_deltas = ("module_node_counts",)
+
+    #: Until 0.27.0 this class overrode ``capture()`` to accept the docstring
+    #: coverage fraction as ``coverage`` and rename it on the way through. The
+    #: override is gone, and the stored name is the only name. Without this
+    #: entry a caller still passing ``coverage=`` would get no error: the base
+    #: ``**extra_metrics`` would record a ``coverage`` metric nobody reads and
+    #: leave ``docstring_coverage`` absent.
+    capture_aliases = {"coverage": "docstring_coverage"}
+
+    # ------------------------------------------------------------------
+    # Capture-time metrics collected by this module
+    # ------------------------------------------------------------------
+
+    def _domain_metrics(self, stats: dict[str, Any]) -> dict[str, Any]:
+        """Collect the metrics this module gathers for itself.
+
+        Called by the inherited ``capture()``. Overriding this rather than
+        ``capture()`` is deliberate: a ``capture()`` override has to restate the
+        base signature, and restating it is what let ``key=`` fall into
+        ``**extra_metrics`` and ship 0.25.0 with every snapshot keyed on a tree
+        hash.
+
+        :param stats: Graph stats passed to ``capture()``; unused here, the
+            counts come from SQLite.
+        :return: ``{"module_node_counts": {module_path: node_count}}``, empty
+                 if no SQLite graph is configured.
+        """
+        return {"module_node_counts": self._collect_module_node_counts()}
+
+    # ------------------------------------------------------------------
+    # 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 {}