Skip to content

160-tool MCP server for real-time global intelligence from free public APIs: markets, liquidity, prediction markets, SEC filings, conflict, military, aircraft-cohort early warning, migration and border flows, cyber, climate, news and more. Dated observation history, 29 research prompts, cited briefs, geofences, SSE dashboard. MIT, no paid API keys.

Source health: mark a cache file moved or replaced under the server

Phoenix Agent (mac-studio)bf634d3cbb74
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3d55991..0f57d55 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -366,6 +366,12 @@ source here, and no proxy is substituted for any of these measures.
forms, treats hyphens as underscores and needs no word boundary in
front. Whole and decimal numbers take ASCII digits only, and a value
over 200 characters is refused instead of cut.
+- A cache file moved, deleted or replaced while the server held it open
+ kept answering from the open handle, and source health reported it as
+ the shared cache. `cache.moved` now marks it (the path is gone, or is
+ not the file source health first read), the verdict says the numbers
+ come from a file no other process shares, and the scope notes say a
+ replacement made before the first read is not detected.
### Added: tropical cyclone forecast tracks
- `intel_cyclones` and `intel_jtwc_cyclones` take `include_forecast`
diff --git a/README.md b/README.md
index 9491118..94b5a06 100644
--- a/README.md
+++ b/README.md
@@ -193,7 +193,7 @@ cannot support, before it calls anything.
| Resource | Type | What it holds |
|----------|------|---------------|
| `intel://guide` | Markdown | How to ask a strong question (name the period, the comparison, the measure and the place), what an answer contains, what this server will not do, the worked prompts, and every tool grouped by domain. Built from the live tool registry on each read, so it always matches `tools/list`. |
-| `intel://guide/source-health` | JSON | Open circuit breakers, stale serves, cache freshness per source prefix, and which keyed sources have their variables set (names only, never values). Reading it starts no fetch. Breaker state covers this server process only; the collector keeps its own. `failing_sources` names every source whose last call failed, before or after its breaker opens. A `verdict` line says when there is nothing to go on yet (no requests made and an empty cache). A cache that cannot be read is reported as `cache.available: false` with the error, next to the rest of the snapshot, and `cache.requested_path` and `cache.fell_back` show when the configured database could not be opened and a temporary one is in use. |
+| `intel://guide/source-health` | JSON | Open circuit breakers, stale serves, cache freshness per source prefix, and which keyed sources have their variables set (names only, never values). Reading it starts no fetch. Breaker state covers this server process only; the collector keeps its own. `failing_sources` names every source whose last call failed, before or after its breaker opens. A `verdict` line says when there is nothing to go on yet (no requests made and an empty cache). A cache that cannot be read is reported as `cache.available: false` with the error, next to the rest of the snapshot, and `cache.requested_path` and `cache.fell_back` show when the configured database could not be opened and a temporary one is in use. `cache.moved` is true when the cache file was moved, deleted or replaced while the server holds it open. |
| `intel://guide/measures` | Markdown | Amount outstanding versus flow, growth versus acceleration, percentage points, seasonal adjustment, observation versus publication versus collection dates, revisions, correlation and timing offsets, composite scores, and why missing data is not zero. |
**29 prompts**, each a worked research question that names the tools to
diff --git a/src/world_intel_mcp/guide.py b/src/world_intel_mcp/guide.py
index 2b6a8bb..275a079 100644
--- a/src/world_intel_mcp/guide.py
+++ b/src/world_intel_mcp/guide.py
@@ -26,8 +26,10 @@ Gaps / not covered:
so in its ``scope`` field.
- ``keyed_sources`` reports whether a variable is set, not whether the
key is valid or within quota.
-- A cache file moved or deleted while the server holds it open keeps
- answering from the open handle; source health cannot tell.
+- A cache file moved, deleted or replaced while the server holds it open
+ keeps answering from the open handle. Source health marks it
+ (cache.moved) by comparing the path with the file it first read, so a
+ replacement made before the first source-health read is not detected.
- The guide states no count of tools that return no failure marker under
a total outage, because the count changes as tools are added. A review
sweep at 7782d22 (137 of its 139 tools, each in a fresh process with a
@@ -43,6 +45,7 @@ import os
import re
import sqlite3
import time
+import weakref
from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Any, Mapping
@@ -473,7 +476,11 @@ _HEALTH_SCOPE = (
"cache.requested_path is the database this process was configured to "
"use; when it could not be opened, cache.fell_back is true and db_path "
"is a temporary database that no other process shares. "
- "cache.available is false when the database could not be read at all.",
+ "cache.available is false when the database could not be read at all. "
+ "cache.moved is true when the file at db_path is gone, or is not the "
+ "file this process first read, while this process still holds the old "
+ "one open: its numbers then come from a file no other process shares. "
+ "A file replaced before this resource was first read is not detected.",
"keyed_sources says whether each variable is set in this server's "
"environment. It never shows values and does not check that a key works.",
"Not read here: vector store statistics (intel_vector_stats) and the "
@@ -481,12 +488,38 @@ _HEALTH_SCOPE = (
)
+# The file each cache object's database was on when source health first
+# read it. A moved or replaced file keeps answering through the open
+# handle, so the path is compared with this on every read.
+_FIRST_FILE: "weakref.WeakKeyDictionary[Any, tuple[int, int]]" = weakref.WeakKeyDictionary()
+
+
+def _file_identity(path: Any) -> tuple[int, int] | None:
+ try:
+ st = os.stat(path)
+ except OSError:
+ return None
+ return (st.st_dev, st.st_ino)
+
+
+def _cache_moved(cache: Any) -> bool:
+ now = _file_identity(cache.db_path)
+ if now is None:
+ return True
+ try:
+ first = _FIRST_FILE.setdefault(cache, now)
+ except TypeError:
+ return False
+ return first != now
+
+
def _read_cache(cache: Any) -> tuple[dict[str, Any], dict[str, Any] | None]:
"""Cache statistics and per-prefix freshness, or why they are unreadable.
A broken database (table missing, file corrupt, disk error) becomes
``available: false`` with the error text, so the rest of the health
- snapshot still reaches the caller.
+ snapshot still reaches the caller. ``moved`` marks a database file that
+ was moved, deleted or replaced while this process holds it open.
"""
paths = {
"db_path": str(cache.db_path),
@@ -498,7 +531,7 @@ def _read_cache(cache: Any) -> tuple[dict[str, Any], dict[str, Any] | None]:
by_prefix = cache.freshness()
except (sqlite3.Error, OSError) as exc:
return {"available": False, "error": f"{type(exc).__name__}: {exc}", **paths}, None
- return {"available": True, **stats, **paths}, by_prefix
+ return {"available": True, **stats, **paths, "moved": _cache_moved(cache)}, by_prefix
def _failing_sources(breakers: dict[str, Any]) -> list[str]:
@@ -544,6 +577,12 @@ def _verdict(breakers: dict[str, Any], cache_info: dict[str, Any]) -> str:
"; the configured cache could not be opened, so this process uses "
"a temporary cache of its own"
)
+ if cache_info.get("moved"):
+ verdict += (
+ "; the cache file at db_path was moved or replaced while this "
+ "process held it open, so its cache numbers come from a file no "
+ "other process shares"
+ )
return verdict
diff --git a/src/world_intel_mcp/tests/test_guide.py b/src/world_intel_mcp/tests/test_guide.py
index 9ce24c2..8f3b32f 100644
--- a/src/world_intel_mcp/tests/test_guide.py
+++ b/src/world_intel_mcp/tests/test_guide.py
@@ -1822,3 +1822,37 @@ def test_prompt_refuses_an_overlong_value_instead_of_cutting_it() -> None:
assert "y" * 200 in guide_prompts.render(prompt, {"country": "y" * 200})
with pytest.raises(guide_prompts.PromptArgumentError, match="longer than 200 characters"):
guide_prompts.render(prompt, {"country": "y" * 201})
+
+
+def test_source_health_marks_a_cache_file_moved_or_replaced_under_it(tmp_path) -> None:
+ """The open handle keeps answering after the file is moved or a new
+ file takes its path; source health must say so."""
+ path = tmp_path / "held.db"
+ cache = Cache(db_path=path)
+ other = None
+ try:
+ cache.set("markets:quote:SPY", {"price": 1}, 60)
+ before = guide.source_health(CircuitBreaker(), cache)
+ assert before["cache"]["moved"] is False
+ assert "moved or replaced" not in before["verdict"]
+
+ for suffix in ("", "-wal", "-shm"):
+ moved_from = Path(f"{path}{suffix}")
+ if moved_from.exists():
+ moved_from.rename(tmp_path / f"away.db{suffix}")
+ gone = guide.source_health(CircuitBreaker(), cache)
+ assert (gone["cache"]["available"], gone["cache"]["total_entries"]) == (True, 1)
+ assert gone["cache"]["moved"] is True
+ assert "moved or replaced while this process held it open" in gone["verdict"]
+
+ other = Cache(db_path=path)
+ other.set("conflict:acled:SDN", {"events": []}, 60)
+ replaced = guide.source_health(CircuitBreaker(), cache)
+ assert replaced["cache"]["moved"] is True
+ assert guide.source_health(CircuitBreaker(), other)["cache"]["moved"] is False
+ finally:
+ cache.close()
+ if other is not None:
+ other.close()
+ scope = " ".join(guide._HEALTH_SCOPE)
+ assert "cache.moved is true when the file at db_path is gone" in scope