From 5b8a6ad5ec25b765a2e17836e58340a17e589ed0 Mon Sep 17 00:00:00 2001
From: root <diego.ecab@gmail.com>
Date: Sat, 25 Apr 2026 23:38:29 -0300
Subject: [PATCH] Lookup index auto-invalidates on KB updates + manual rebuild
 flag
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Diego asked: does the persisted ``archcenter-refs-index.json`` auto-
update when the KB is updated? Partially — mtime on the cache root
catches add/remove of subdirs (POSIX), but NOT changes to files
INSIDE existing subdirs (description.md added, .drawio replaced).

Two fixes:

1. Both KB-update tools now ``touch`` ``kb/diagram/assets/archcenter-refs``
   when they finish a run that produced changes:
   - ``archcenter_description_fetcher.py`` after fetched > 0
   - ``archcenter_zip_downloader.py`` after downloaded / extract /
     overwrite events
   The touch bumps the parent mtime, which the next lookup detects
   and uses to rebuild its persisted index. Closes the silent-drift
   case where description.md fetches landed but the index didn't
   notice.

2. ``archcenter_pattern_lookup.py --rebuild-index`` flag — escape
   hatch for manual KB edits (someone replaces a cached .drawio by
   hand) where neither tool ran. Removes the stale index file before
   the lookup, forcing a cold rebuild.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 kb/diagram/assets/archcenter-refs-index.json |  2 +-
 tools/archcenter_description_fetcher.py      | 10 ++++++++++
 tools/archcenter_pattern_lookup.py           |  8 ++++++++
 tools/archcenter_zip_downloader.py           | 10 ++++++++++
 4 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/kb/diagram/assets/archcenter-refs-index.json b/kb/diagram/assets/archcenter-refs-index.json
index 3ec89f1..364e4f6 100644
--- a/kb/diagram/assets/archcenter-refs-index.json
+++ b/kb/diagram/assets/archcenter-refs-index.json
@@ -1,5 +1,5 @@
 {
-  "cache_dir_mtime": 1777161774.8360987,
+  "cache_dir_mtime": 1777171058.9167857,
   "entries": {
     "active-data-guard-far-sync-dba-oracle": {
       "drawio": "kb/diagram/assets/archcenter-refs/active-data-guard-far-sync-dba-oracle/active-data-guard-far-sync-dba.drawio",
diff --git a/tools/archcenter_description_fetcher.py b/tools/archcenter_description_fetcher.py
index cd96a0c..7f1f02c 100644
--- a/tools/archcenter_description_fetcher.py
+++ b/tools/archcenter_description_fetcher.py
@@ -169,6 +169,16 @@ def main() -> None:
         print(f"  {s:25s}  {n}", file=sys.stderr)
     print(f"\nReport: {args.report.relative_to(PROJECT_ROOT)}", file=sys.stderr)
 
+    # Bump CACHE_DIR mtime so archcenter_pattern_lookup invalidates its
+    # persisted JSON index — POSIX doesn't propagate child-file changes
+    # (e.g. new _description.md inside an existing slug) to the parent
+    # dir's mtime, so we touch it explicitly.
+    if counts.get("fetched"):
+        try:
+            CACHE_DIR.touch(exist_ok=True)
+        except OSError:
+            pass
+
 
 if __name__ == "__main__":
     main()
diff --git a/tools/archcenter_pattern_lookup.py b/tools/archcenter_pattern_lookup.py
index 1289b98..04bae0f 100644
--- a/tools/archcenter_pattern_lookup.py
+++ b/tools/archcenter_pattern_lookup.py
@@ -402,7 +402,15 @@ def main() -> None:
                         "before scoring (opt-in; requires "
                         "ANTHROPIC_API_KEY). Useful for natural-language "
                         "queries the synonym table doesn't cover.")
+    parser.add_argument("--rebuild-index", action="store_true",
+                        help="Force-rebuild the cached archcenter-refs "
+                        "index (kb/diagram/assets/archcenter-refs-index.json). "
+                        "Use after a manual KB edit if mtime didn't bump.")
     args = parser.parse_args()
+    if args.rebuild_index and CACHE_INDEX_FILE.exists():
+        CACHE_INDEX_FILE.unlink()
+        print(f"[lookup] removed stale index at {CACHE_INDEX_FILE.relative_to(PROJECT_ROOT)}",
+              file=sys.stderr)
 
     queries: list[str] = list(args.queries)
     if args.query:
diff --git a/tools/archcenter_zip_downloader.py b/tools/archcenter_zip_downloader.py
index 9915ce1..29caa32 100644
--- a/tools/archcenter_zip_downloader.py
+++ b/tools/archcenter_zip_downloader.py
@@ -211,6 +211,16 @@ def main() -> None:
         print(f"  {status:30s}  {n}", file=sys.stderr)
     print(f"\nReport: {args.report.relative_to(PROJECT_ROOT)}", file=sys.stderr)
 
+    # Bump cache-dir mtime so the pattern-lookup index invalidates.
+    # New downloads create new subdirs (POSIX bumps the parent mtime),
+    # but re-downloads or unzip-overwrites of existing slugs do not —
+    # so we touch explicitly.
+    if any(counts.get(k) for k in ("downloaded", "zip_error", "no_drawio_after_extract")):
+        try:
+            args.cache_dir.touch(exist_ok=True)
+        except OSError:
+            pass
+
 
 if __name__ == "__main__":
     main()