chore: v0.3.4 — dedup CLI store-locking helper, doc summary helper

Two safe extractions identified by jscpd+pylint+PMD clone analysis:

- cli/_helpers.py — extract open_store_or_exit, used by main.py and
  setup_wizard.py. Both copies were verbatim duplicates with no other
  callers.
- core/docs.py — extract summarize_doc, used by retrieval/graph.py
  (8 callers) and pipeline/advanced_reason.py (2 callers). Both were
  identical static methods returning the same {id, title, type, project,
  created_at} dict.

Also fixes pre-existing version drift: v0.3.3 bumped pyproject.toml but
forgot src/cortex/__init__.py, leaving __version__ = '0.3.2'. Synced to
0.3.4.

No behavior change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: grayisnotacolor

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.4] — 2026-05-01
+
+### Changed
+
+- **Deduplicated CLI store-locking helper** — `_open_store_or_exit` was defined verbatim in both `cli/main.py` and `cli/setup_wizard.py`; extracted to shared `cli/_helpers.py::open_store_or_exit`. No behavior change.
+- **Deduplicated document summary helper** — `AdvancedReasoner._to_chain_entry` and `GraphQueries._summarize` produced identical compact-doc dicts; extracted to shared `core/docs.py::summarize_doc`. No behavior change.
+
+### Fixed
+
+- **`__version__` now matches `pyproject.toml`** — v0.3.3 forgot to bump `cortex/__init__.py`, leaving `__version__ = "0.3.2"`. Now synced to `0.3.4`.
+
 ## [0.3.3] — 2026-04-20
 
 ### Fixed

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "abbacus-cortex"
-version = "0.3.3"
+version = "0.3.4"
 description = "Cognitive knowledge system with formal ontology, reasoning, and intelligence serving"
 readme = "README.md"
 authors = [

src/cortex/__init__.py

@@ -1,3 +1,3 @@
 """Cortex — Cognitive knowledge system."""
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"

src/cortex/cli/_helpers.py

@@ -0,0 +1,23 @@
+"""Shared CLI helpers.
+
+Single chokepoint utilities used by multiple CLI entry points (the main
+typer app and the setup wizard). Keeping them here prevents the helpers
+from drifting independently in each module.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from cortex.core.config import CortexConfig
+from cortex.core.errors import StoreLockedError
+from cortex.db.store import Store
+
+
+def open_store_or_exit(config: CortexConfig) -> Store:
+    """Open a Store, exiting cleanly with a user-friendly message if the graph DB is locked."""
+    try:
+        return Store(config)
+    except StoreLockedError as e:
+        typer.secho(str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from e

src/cortex/cli/main.py

@@ -12,6 +12,7 @@
 
 import typer
 
+from cortex.cli._helpers import open_store_or_exit
 from cortex.core.config import CortexConfig, load_config
 from cortex.core.constants import KNOWLEDGE_TYPES
 from cortex.core.errors import StoreLockedError
@@ -61,18 +62,6 @@ def _global_options(
     _mcp_probe_done = False
 
 
-def _open_store_or_exit(config: CortexConfig) -> Store:
-    """Open a Store, exiting cleanly with a user-friendly message if the graph DB is locked.
-
-    This is the single chokepoint for surfacing StoreLockedError to CLI users.
-    """
-    try:
-        return Store(config)
-    except StoreLockedError as e:
-        typer.secho(str(e), fg=typer.colors.RED, err=True)
-        raise typer.Exit(1) from e
-
-
 # ─── Phase 3 helpers — MCP client routing ──────────────────────────────────
 
 
@@ -334,7 +323,7 @@ def _get_store(*, must_init: bool = True) -> Store:
 
     config = load_config()
     setup_logging(level=config.log_level, json_output=False)
-    store = _open_store_or_exit(config)
+    store = open_store_or_exit(config)
 
     # Auto-initialize if data dir has stores
     try:

src/cortex/cli/setup_wizard.py

@@ -17,8 +17,8 @@
 
 import typer
 
+from cortex.cli._helpers import open_store_or_exit
 from cortex.core.config import CortexConfig, load_config
-from cortex.core.errors import StoreLockedError
 from cortex.core.logging import setup_logging
 from cortex.db.store import Store
 from cortex.ontology.resolver import find_ontology
@@ -79,14 +79,6 @@ def _echo(msg: str = "") -> None:
     typer.echo(msg)
 
 
-def _open_store_or_exit(config: CortexConfig) -> Store:
-    try:
-        return Store(config)
-    except StoreLockedError as e:
-        typer.secho(str(e), fg=typer.colors.RED, err=True)
-        raise typer.Exit(1) from e
-
-
 def _test_llm(config: CortexConfig, model: str, api_key: str, provider: str) -> tuple[bool, str]:
     """Attempt an LLM test call. Returns (success, message)."""
     from cortex.services.llm import LLMClient
@@ -135,7 +127,7 @@ def _step_data_dir(config: CortexConfig) -> None:
 def _step_stores(config: CortexConfig) -> Store:
     """Step 2: Initialize stores and load ontology."""
     _echo("\n[2/7] Stores & ontology")
-    store = _open_store_or_exit(config)
+    store = open_store_or_exit(config)
     try:
         ontology_path = find_ontology()
         store.initialize(ontology_path)

src/cortex/core/docs.py

@@ -0,0 +1,16 @@
+"""Shared document helpers used across retrieval and pipeline layers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def summarize_doc(doc: dict[str, Any]) -> dict[str, Any]:
+    """Compact summary of a knowledge object — id, title, type, project, created_at."""
+    return {
+        "id": doc.get("id", ""),
+        "title": doc.get("title", ""),
+        "type": doc.get("type", ""),
+        "project": doc.get("project", ""),
+        "created_at": doc.get("created_at", ""),
+    }

src/cortex/pipeline/advanced_reason.py

@@ -14,6 +14,7 @@
 import datetime
 from typing import Any
 
+from cortex.core.docs import summarize_doc
 from cortex.core.logging import get_logger
 from cortex.db.store import Store
 from cortex.services.llm import LLMClient
@@ -262,7 +263,7 @@ def assemble_causal_chain(self, obj_id: str) -> list[dict[str, Any]]:
         # Add the object itself
         doc = self.store.content.get(obj_id)
         if doc:
-            chain.append(self._to_chain_entry(doc))
+            chain.append(summarize_doc(doc))
 
         # Trace forward (effects)
         self._trace_chain(obj_id, chain, visited, "ledTo", "outgoing")
@@ -289,7 +290,7 @@ def _trace_chain(
                 if other_id not in visited:
                     doc = self.store.content.get(other_id)
                     if doc:
-                        chain.append(self._to_chain_entry(doc))
+                        chain.append(summarize_doc(doc))
                         self._trace_chain(
                             other_id,
                             chain,
@@ -299,12 +300,3 @@ def _trace_chain(
                             max_depth - 1,
                         )
 
-    @staticmethod
-    def _to_chain_entry(doc: dict[str, Any]) -> dict[str, Any]:
-        return {
-            "id": doc.get("id", ""),
-            "title": doc.get("title", ""),
-            "type": doc.get("type", ""),
-            "project": doc.get("project", ""),
-            "created_at": doc.get("created_at", ""),
-        }

src/cortex/retrieval/graph.py

@@ -12,6 +12,7 @@
 
 from typing import Any
 
+from cortex.core.docs import summarize_doc
 from cortex.core.logging import get_logger
 from cortex.db.store import Store
 
@@ -37,7 +38,7 @@ def causal_chain(self, obj_id: str, max_depth: int = 10) -> list[dict[str, Any]]
         # Add the starting object
         start = self.store.content.get(obj_id)
         if start:
-            chain.append(self._summarize(start))
+            chain.append(summarize_doc(start))
         # Fresh visited for forward — includes backward nodes (prevents
         # duplicates) but excludes the start node so forward traversal
         # can examine its outgoing ledTo edges.
@@ -73,7 +74,7 @@ def _traverse_causal(
             if is_backward or is_forward:
                 other = self.store.content.get(rel["other_id"])
                 if other and rel["other_id"] not in visited:
-                    chain.append(self._summarize(other))
+                    chain.append(summarize_doc(other))
                     self._traverse_causal(rel["other_id"], chain, visited, remaining - 1, direction)
 
     def contradiction_map(self, scope: str | None = None) -> list[dict[str, Any]]:
@@ -128,7 +129,7 @@ def entity_neighborhood(self, entity_name: str, *, max_hops: int = 2) -> dict[st
         for mid in mention_ids:
             doc = self.store.content.get(mid)
             if doc:
-                direct_objects.append(self._summarize(doc))
+                direct_objects.append(summarize_doc(doc))
 
         # Extended neighborhood (hop 2): objects connected to the direct objects
         connections = []
@@ -144,7 +145,7 @@ def entity_neighborhood(self, entity_name: str, *, max_hops: int = 2) -> dict[st
                         if other:
                             connections.append(
                                 {
-                                    **self._summarize(other),
+                                    **summarize_doc(other),
                                     "via": mid,
                                     "via_rel": rel["rel_type"],
                                 }
@@ -171,7 +172,7 @@ def evolution_timeline(self, obj_id: str) -> list[dict[str, Any]]:
         # Add current
         current = self.store.content.get(obj_id)
         if current:
-            chain.append(self._summarize(current))
+            chain.append(summarize_doc(current))
 
         # Go forward (find what supersedes this) — fresh visited
         # excludes start node so forward traversal can examine its edges
@@ -205,7 +206,7 @@ def _traverse_supersedes(
                 ):
                     other = self.store.content.get(rel["other_id"])
                     if other:
-                        chain.append(self._summarize(other))
+                        chain.append(summarize_doc(other))
                         self._traverse_supersedes(rel["other_id"], chain, visited, direction)
             elif (
                 direction == "forward"
@@ -215,7 +216,7 @@ def _traverse_supersedes(
             ):
                 other = self.store.content.get(rel["other_id"])
                 if other:
-                    chain.append(self._summarize(other))
+                    chain.append(summarize_doc(other))
                     self._traverse_supersedes(rel["other_id"], chain, visited, direction)
 
     def project_overview(self, project: str) -> dict[str, Any]:
@@ -255,18 +256,8 @@ def project_overview(self, project: str) -> dict[str, Any]:
         return {
             "project": project,
             "object_count": len(objects),
-            "objects": [self._summarize(obj) for obj in objects],
+            "objects": [summarize_doc(obj) for obj in objects],
             "entities": entities,
             "edges": edges,
         }
 
-    @staticmethod
-    def _summarize(doc: dict[str, Any]) -> dict[str, Any]:
-        """Create a compact summary of a document."""
-        return {
-            "id": doc.get("id", ""),
-            "title": doc.get("title", ""),
-            "type": doc.get("type", ""),
-            "project": doc.get("project", ""),
-            "created_at": doc.get("created_at", ""),
-        }