feat: node-level text/summary versioning with deferred regeneration

Decouples "this node changed" from "this node's summary is current", so a
small edit no longer prices a summary regeneration immediately.

Each MD node carries two counters:
  text_version     bumps on every detected content change (cheap, sha256)
  summary_version  the text_version the stored summary was generated from
A node is stale iff the two differ.

update() now does NO LLM work at all. It diffs section hashes, bumps
text_version on changed/added nodes, and leaves summary_version behind.
Regeneration is deferred to the next read (get_document_structure), where
every stale node is regenerated in one batch and summary_version catches
up. N edits between two reads therefore cost one regeneration, not N.

This also removes the previous ancestor-expansion pass, which was a no-op:
a parent's `text` excludes its children, so re-summarizing an ancestor fed
the model byte-identical input and produced the same summary at full cost.
Parent summaries are still generated from each node's own text -- there is
no child-to-parent roll-up, by design.

Versions are monotonic across re-index. index() reuses the doc_id for a
known path, so versions are carried forward and only bumped where the
section hash actually moved; a reader holding version N never sees it drop.

Also fixes a bug this exposed: _reconcile_summaries called _save_doc, which
evicts `structure` from memory for lazy reload, so get_document_structure
then served an empty tree. A retrieval against a doc with any stale node
got `[]` and answered from hallucinated line numbers instead of erroring.
Reconcile now reloads after saving.

Scope: MD only. update() already rejects PDFs, and PDF nodes carry no
section hashes, so version fields are simply absent there and the staleness
check tolerates that.

Deliberately not included: a semantic-change gate (embedding or LLM) to
suppress regeneration for immaterial edits. Dropping propagation and
deferring to read already removed both cost drivers, so the remaining
saving is marginal and a predicate that can under-fire on a negation or a
changed number risks the silent staleness this design exists to prevent.

Tests: 8 new cases, summarizer stubbed so they run offline with no API key.
15 passing.

Author: harshrathod0585

pageindex/client.py

@@ -22,7 +22,7 @@
     remove_fields,
     hash_text,
     compute_section_hashes,
-    find_ancestors,
+    walk_with_paths,
     write_node_id,
     format_structure,
 )
@@ -132,7 +132,30 @@ def index(self, file_path: str, mode: str = "auto") -> str:
             # Compute hashes from the raw file to enable incremental update().
             _md_content = open(file_path, encoding='utf-8').read()
             _node_list, _md_lines = extract_nodes_from_markdown(_md_content)
+
             _flat_nodes = extract_node_text_content(_node_list, _md_lines)
+            _new_hashes = compute_section_hashes(_flat_nodes)
+            # Re-indexing reuses the doc_id, so versions must carry forward:
+            # a reader holding version N must never see it go backwards.
+            if doc_id in self.documents and self.workspace:
+                self._ensure_doc_loaded(doc_id)
+            _prev = self.documents.get(doc_id, {})
+            _old_versions = {
+                p: n.get('text_version', 1)
+                for p, n in walk_with_paths(_prev.get('structure') or [])
+            }
+            _old_hashes = _prev.get('section_hashes') or {}
+            for _p, _n in walk_with_paths(result['structure']):
+                _old_tv = _old_versions.get(_p)
+                if _old_tv is None:
+                    _tv = 1
+                elif _old_hashes.get(_p) != _new_hashes.get(_p):
+                    _tv = _old_tv + 1
+                else:
+                    _tv = _old_tv
+                # index() regenerates every summary, so nothing is left stale.
+                _n['text_version'] = _tv
+                _n['summary_version'] = _tv
             self.documents[doc_id] = {
                 'id': doc_id,
                 'type': 'md',
@@ -142,7 +165,7 @@ def index(self, file_path: str, mode: str = "auto") -> str:
                 'line_count': result.get('line_count', 0),
                 'structure': result['structure'],
                 'file_hash': hash_text(_md_content),
-                'section_hashes': compute_section_hashes(_flat_nodes),
+                'section_hashes': _new_hashes,
             }
         else:
             raise ValueError(f"Unsupported file format for: {file_path}")
@@ -286,53 +309,40 @@ def update(self, doc_id: str) -> dict:
         deleted = old_keys - new_keys
         changed = {p for p in new_keys & old_keys if new_hashes[p] != old_hashes[p]}
 
-        # Dirty sections plus the ancestors of each (roll-up summaries).
         dirty = changed | added
-        to_summarize = set(dirty)
-        for path in dirty:
-            to_summarize.update(find_ancestors(path))
-
-        # Reuse cached summaries for clean sections. The persisted tree has no
-        # title_path, so rebuild it to match the keys used by new_nodes.
-        old_summary_map = {}
-
-        def _collect_summaries(nodes, prefix=''):
-            for n in nodes:
-                path = f"{prefix} > {n['title']}" if prefix else n['title']
-                old_summary_map[path] = n.get('summary') or n.get('prefix_summary', '')
-                _collect_summaries(n.get('nodes', []), path)
-
-        _collect_summaries(doc.get('structure', []))
-
-        async def _identity(val):
-            return val
-
-        async def _regenerate():
-            tasks = {}
-            for path, node in {n['title_path']: n for n in new_nodes}.items():
-                if path in to_summarize:
-                    tasks[path] = get_node_summary(node, summary_token_threshold=200, model=self.model)
-                else:
-                    tasks[path] = _identity(old_summary_map.get(path, ''))
-            return {path: await coro for path, coro in tasks.items()}
 
-        try:
-            asyncio.get_running_loop()
-            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
-                summaries = pool.submit(asyncio.run, _regenerate()).result()
-        except RuntimeError:
-            summaries = asyncio.run(_regenerate())
+        # Carry summaries and versions forward from the old tree.
+        old_by_path = dict(walk_with_paths(doc.get('structure', [])))
+        old_summary_map = {
+            p: n.get('summary') or n.get('prefix_summary', '')
+            for p, n in old_by_path.items()
+        }
 
+        # No LLM work here. Bump text_version on dirty sections and leave
+        # summary_version behind, marking the summary stale; regeneration is
+        # deferred to read time (see _reconcile_summaries). Repeated updates
+        # between two reads therefore cost one regeneration, not one each.
         for node in new_nodes:
-            node['summary'] = summaries.get(node['title_path'], '')
+            path = node['title_path']
+            old = old_by_path.get(path)
+            node['summary'] = old_summary_map.get(path, '')
+            if old is None:
+                # Newly added: no summary yet, so it starts out stale.
+                node['text_version'] = 1
+                node['summary_version'] = 0
+            else:
+                old_tv = old.get('text_version', 1)
+                node['text_version'] = old_tv + 1 if path in dirty else old_tv
+                node['summary_version'] = old.get('summary_version', old_tv)
 
         # Rebuild the tree with fresh node ids.
         new_structure = build_tree_from_nodes(new_nodes)
         split_summary_fields(new_structure)
         write_node_id(new_structure)
         new_structure = format_structure(
             new_structure,
-            order=['title', 'node_id', 'line_num', 'summary', 'prefix_summary', 'text', 'nodes'],
+            order=['title', 'node_id', 'line_num', 'text_version', 'summary_version',
+                   'summary', 'prefix_summary', 'text', 'nodes'],
         )
 
         doc['structure'] = new_structure
@@ -360,10 +370,61 @@ def get_document(self, doc_id: str) -> str:
         """Return document metadata JSON."""
         return get_document(self.documents, doc_id)
 
+    def _reconcile_summaries(self, doc_id: str) -> int:
+        """Regenerate summaries whose text has moved on, and return how many.
+
+        A node is stale when summary_version != text_version. update() only
+        bumps text_version, so this is where deferred regeneration is paid --
+        on the first read after an edit, batched across every stale node.
+        """
+        if self.workspace:
+            self._ensure_doc_loaded(doc_id)
+        doc = self.documents.get(doc_id)
+        if not doc or doc.get('type') != 'md':
+            return 0
+
+        stale = [
+            n for _, n in walk_with_paths(doc.get('structure', []))
+            if n.get('summary_version') != n.get('text_version')
+        ]
+        if not stale:
+            return 0
+
+        async def _run():
+            return await asyncio.gather(*(
+                get_node_summary(n, summary_token_threshold=200, model=self.model)
+                for n in stale
+            ))
+
+        try:
+            asyncio.get_running_loop()
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                summaries = pool.submit(asyncio.run, _run()).result()
+        except RuntimeError:
+            summaries = asyncio.run(_run())
+
+        for node, summary in zip(stale, summaries):
+            key = 'prefix_summary' if node.get('nodes') else 'summary'
+            node.pop('prefix_summary' if key == 'summary' else 'summary', None)
+            node[key] = summary
+            node['summary_version'] = node['text_version']
+
+        if self.workspace:
+            # _save_doc evicts structure from memory for lazy reload; pull it
+            # back so callers see the tree we just reconciled, not an empty one.
+            self._save_doc(doc_id)
+            self._ensure_doc_loaded(doc_id)
+        return len(stale)
+
     def get_document_structure(self, doc_id: str) -> str:
-        """Return document tree structure JSON (without text fields)."""
+        """Return document tree structure JSON (without text fields).
+
+        Stale summaries are regenerated first, so a reader never sees a
+        summary that describes text the document no longer contains.
+        """
         if self.workspace:
             self._ensure_doc_loaded(doc_id)
+        self._reconcile_summaries(doc_id)
         return get_document_structure(self.documents, doc_id)
 
     def get_page_content(self, doc_id: str, pages: str) -> str:

pageindex/page_index_md.py

@@ -230,10 +230,11 @@ def build_tree_from_nodes(node_list):
             'line_num': node['line_num'],
             'nodes': []
         }
-        # Callers that summarize before building the tree (e.g. incremental
-        # update) would otherwise have their summaries dropped here.
-        if 'summary' in node:
-            tree_node['summary'] = node['summary']
+        # Callers that summarize or version nodes before building the tree
+        # (e.g. incremental update) would otherwise have those fields dropped.
+        for field in ('summary', 'text_version', 'summary_version'):
+            if field in node:
+                tree_node[field] = node[field]
         node_counter += 1
 
         while stack and stack[-1][1] >= current_level:

pageindex/utils.py

@@ -723,6 +723,19 @@ def compute_section_hashes(node_list: list) -> dict:
     return {node["title_path"]: hash_text(node.get("text", "")) for node in node_list}
 
 
+def walk_with_paths(nodes, prefix=""):
+    """Yield (title_path, node) for every node in a tree.
+
+    The persisted tree stores no title_path; this reconstructs it with the
+    same ' > ' join used by extract_node_text_content, so tree nodes can be
+    matched against the flat node list and section_hashes keys.
+    """
+    for node in nodes:
+        path = f"{prefix} > {node['title']}" if prefix else node["title"]
+        yield path, node
+        yield from walk_with_paths(node.get("nodes", []), path)
+
+
 def find_ancestors(title_path: str) -> list:
     """Return ancestor title paths from root to immediate parent."""
     parts = title_path.split(" > ")