gitvow-provider-facts 0.1.0__tar.gz

gitvow_provider_facts-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 gitvow contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

gitvow_provider_facts-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: gitvow-provider-facts
+Version: 0.1.0
+Summary: gitvow provider answering gate questions from a derived fact store of routes, gates and callers.
+Author-email: Nikhil Bora <nikhil@wirevow.com>
+License: Apache-2.0
+Project-URL: Homepage, https://wirevow.dev/gitvow-provider-facts
+Project-URL: Repository, https://github.com/wirevow/gitvow-provider-facts
+Keywords: gitvow,provenance,policy,ai-agents,git
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: bandit[toml]>=1.7; extra == "dev"
+Requires-Dist: pip-audit>=2.7; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# gitvow-provider-facts
+
+A [gitvow](https://wirevow.dev/gitvow/) provider that answers the gate's questions from a derived fact store of your services: which routes exist, how each is gated, and who calls it.
+
+With it, an agent that adds an endpoint the authorization layer does not cover, or removes one that other services call, is stopped before the file changes, and the message names the whitelist pattern or the calling services.
+
+```sh
+pip install gitvow-provider-facts
+```
+
+```json
+"providers": [{
+  "name": "topology",
+  "command": "gitvow-provider-facts --store /var/lib/topology/facts.db --service orders",
+  "questions": ["route_gate", "route_callers", "gate_bearing"]
+}]
+```
+
+```
+$ gitvow ask route_callers /v1/orders --path src/api/OrdersResource.java
+topology: yes — called by client-orch (OrdersClient.java:88) POST; called by billing-worker (sync.py:41) GET; store built 2026-09-08 (1 day old)
+decision: CONFIRM
+```
+
+No runtime dependencies: Python 3.9+ and sqlite3 from the standard library. The provider holds no knowledge of its own; it reads a store you build. It never writes to the store and never contacts the network.
+
+Documentation: **https://wirevow.dev/gitvow-provider-facts/** · Protocol it implements: [gitvow provider protocol](https://wirevow.dev/gitvow/reference/provider-protocol/)
+
+Apache-2.0.

gitvow_provider_facts-0.1.0/README.md

@@ -0,0 +1,29 @@
+# gitvow-provider-facts
+
+A [gitvow](https://wirevow.dev/gitvow/) provider that answers the gate's questions from a derived fact store of your services: which routes exist, how each is gated, and who calls it.
+
+With it, an agent that adds an endpoint the authorization layer does not cover, or removes one that other services call, is stopped before the file changes, and the message names the whitelist pattern or the calling services.
+
+```sh
+pip install gitvow-provider-facts
+```
+
+```json
+"providers": [{
+  "name": "topology",
+  "command": "gitvow-provider-facts --store /var/lib/topology/facts.db --service orders",
+  "questions": ["route_gate", "route_callers", "gate_bearing"]
+}]
+```
+
+```
+$ gitvow ask route_callers /v1/orders --path src/api/OrdersResource.java
+topology: yes — called by client-orch (OrdersClient.java:88) POST; called by billing-worker (sync.py:41) GET; store built 2026-09-08 (1 day old)
+decision: CONFIRM
+```
+
+No runtime dependencies: Python 3.9+ and sqlite3 from the standard library. The provider holds no knowledge of its own; it reads a store you build. It never writes to the store and never contacts the network.
+
+Documentation: **https://wirevow.dev/gitvow-provider-facts/** · Protocol it implements: [gitvow provider protocol](https://wirevow.dev/gitvow/reference/provider-protocol/)
+
+Apache-2.0.

gitvow_provider_facts-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gitvow-provider-facts"
+version = "0.1.0"
+description = "gitvow provider answering gate questions from a derived fact store of routes, gates and callers."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "Apache-2.0"}
+authors = [{name = "Nikhil Bora", email = "nikhil@wirevow.com"}]
+keywords = ["gitvow", "provenance", "policy", "ai-agents", "git"]
+classifiers = ["Programming Language :: Python :: 3", "License :: OSI Approved :: Apache Software License", "Operating System :: OS Independent"]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.6", "bandit[toml]>=1.7", "pip-audit>=2.7", "mypy>=1.10"]
+
+[project.scripts]
+gitvow-provider-facts = "gitvow_provider_facts.cli:main"
+
+[project.urls]
+Homepage = "https://wirevow.dev/gitvow-provider-facts"
+Repository = "https://github.com/wirevow/gitvow-provider-facts"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "S", "N", "C4", "SIM", "RUF"]
+ignore = ["S101", "S603", "S607", "E501"]
+
+[tool.pytest.ini_options]
+addopts = "-q --cov=gitvow_provider_facts --cov-report=term-missing --cov-fail-under=85"
+testpaths = ["tests"]
+
+[tool.bandit]
+skips = ["B404", "B603", "B607"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

gitvow_provider_facts-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gitvow_provider_facts-0.1.0/src/gitvow_provider_facts/__init__.py

@@ -0,0 +1,8 @@
+"""gitvow provider over a derived fact store (routes, gates, callers)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("gitvow-provider-facts")
+except PackageNotFoundError:  # source tree not installed
+    __version__ = "0.0.0+unknown"

gitvow_provider_facts-0.1.0/src/gitvow_provider_facts/cli.py

@@ -0,0 +1,53 @@
+"""Command line: read a gitvow request on stdin, or answer one question from arguments with `ask`."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .provider import Config, answer
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="gitvow-provider-facts", description="gitvow provider over a fact store.")
+    p.add_argument("--version", action="version", version=f"gitvow-provider-facts {__version__}")
+    p.add_argument("--store", required=True)
+    p.add_argument("--repo", default="")
+    p.add_argument("--service", default="")
+    p.add_argument("--gate-file", action="append", default=[])
+    p.add_argument("--max-age-days", type=float, default=14)
+    sub = p.add_subparsers(dest="cmd")
+    s = sub.add_parser("ask", help="answer one question from arguments (for testing)")
+    s.add_argument("question", choices=["gate_bearing", "route_gate", "route_callers"])
+    s.add_argument("subject")
+    s.add_argument("--path", default="")
+    a = p.parse_args(argv)
+    cfg = Config(a.store, a.repo, a.service, a.gate_file, a.max_age_days)
+    if a.cmd == "ask":
+        req = {
+            "protocol": 1,
+            "question": a.question,
+            "subject": a.subject,
+            "path": a.path or (a.subject if a.question == "gate_bearing" else ""),
+            "repo": "",
+        }
+    else:
+        try:
+            req = json.load(sys.stdin)
+        except json.JSONDecodeError as e:
+            print(f"bad request: {e}", file=sys.stderr)
+            return 2
+    try:
+        out = answer(cfg, req)
+    except FileNotFoundError as e:
+        print(f"store not found: {e}", file=sys.stderr)
+        return 3
+    json.dump(out, sys.stdout)
+    print()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gitvow_provider_facts-0.1.0/src/gitvow_provider_facts/provider.py

@@ -0,0 +1,124 @@
+"""Answer gitvow provider questions from a Store."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+from .store import Store, normalize, route_matches
+
+
+@dataclass
+class Config:
+    store: str
+    repo: str = ""
+    service: str = ""
+    gate_files: list[str] = field(default_factory=list)
+    max_age_days: float = 14
+
+
+def _age_evidence(st: Store, cfg: Config) -> str:
+    days = st.age_days()
+    warn = " (STALE: rebuild the store)" if days > cfg.max_age_days else ""
+    return f"store built {int(days)} day{'s' if int(days) != 1 else ''} ago{warn}"
+
+
+def resolve_route(st: Store, repo: str, literal: str, path: str) -> tuple[str, str]:
+    """Return (full route, how). Combine a method-level literal with the class-level prefix implied by the file."""
+    lit = normalize(literal)
+    known = [normalize(r) for r in st.routes_in_file(repo, path)] if path else []
+    if lit in known:
+        return lit, "exact"
+    # longest common prefix of the file's known routes is the class-level @Path
+    if known:
+        segs = [r.split("/") for r in known]
+        prefix: list[str] = []
+        for parts in zip(*segs):
+            if all(p == parts[0] for p in parts):
+                prefix.append(parts[0])
+            else:
+                break
+        pre = "/".join(prefix)
+        if pre and pre != "/" and not lit.startswith(pre + "/") and lit != pre:
+            return normalize(pre + "/" + lit.lstrip("/")), f"prefix {pre} from {os.path.basename(path)}"
+    return lit, "as written"
+
+
+def answer(cfg: Config, req: dict[str, Any]) -> dict[str, Any]:
+    st = Store(cfg.store)
+    q = req.get("question")
+    subject = str(req.get("subject") or "")
+    path = str(req.get("path") or "")
+    repo = cfg.repo or os.path.basename(str(req.get("repo") or "").rstrip("/"))
+    service = cfg.service or repo
+    age = _age_evidence(st, cfg)
+    if q == "gate_bearing":
+        hit = [g for g in cfg.gate_files if fnmatch.fnmatch(path, g) or path.endswith(g)]
+        if hit:
+            return {"answer": "yes", "evidence": [f"gate-bearing file ({hit[0]})", age], "confidence": 1.0}
+        return {"answer": "no" if cfg.gate_files else "unknown", "evidence": [age], "confidence": 0.5}
+    if q not in ("route_gate", "route_callers"):
+        return {"answer": "unknown", "evidence": ["unsupported question"], "confidence": 0.0}
+    route, how = resolve_route(st, repo, subject, path)
+    resolved = f"resolved to {route} ({how})" if route != normalize(subject) else f"route {route}"
+    if q == "route_callers":
+        callers = st.callers(service, route)
+        if callers:
+            ev = [resolved] + [f"called by {c.text()}" for c in callers[:6]]
+            if len(callers) > 6:
+                ev.append(f"and {len(callers) - 6} more callers")
+            return {"answer": "yes", "evidence": [*ev, age], "confidence": 0.9}
+        return {
+            "answer": "unknown",
+            "evidence": [resolved, f"no recorded callers into service {service}", age],
+            "confidence": 0.5,
+        }
+    gates = st.gates(repo, route)
+    if gates:
+        exposed = [g for g in gates if g.exposed]
+        if exposed:
+            g = exposed[0]
+            return {
+                "answer": "yes",
+                "evidence": [resolved, f"recorded gate: {g.classification}", f"declared in {g.file}", age],
+                "confidence": 0.9,
+            }
+        return {
+            "answer": "no",
+            "evidence": [resolved, f"recorded gate: {gates[0].classification}", age],
+            "confidence": 0.9,
+        }
+    if not st.has_gate_data(repo):
+        return {
+            "answer": "unknown",
+            "evidence": [resolved, f"no gate classification recorded for repo {repo}", age],
+            "confidence": 0.3,
+        }
+    for pattern, authenticated in st.whitelist_patterns(repo):
+        if route_matches(pattern, route):
+            if authenticated:
+                return {
+                    "answer": "no",
+                    "evidence": [resolved, f"new route; covered by authenticated whitelist pattern {pattern}", age],
+                    "confidence": 0.8,
+                }
+            return {
+                "answer": "yes",
+                "evidence": [
+                    resolved,
+                    f"new route; whitelist pattern {pattern} makes it OPEN without authentication",
+                    age,
+                ],
+                "confidence": 0.8,
+            }
+    return {
+        "answer": "yes",
+        "evidence": [
+            resolved,
+            "new route; no whitelist pattern covers it, so the gate would return 403 until it is whitelisted",
+            age,
+        ],
+        "confidence": 0.7,
+    }

gitvow_provider_facts-0.1.0/src/gitvow_provider_facts/store.py

@@ -0,0 +1,137 @@
+"""Read-only queries over the fact store."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import re
+import sqlite3
+import time
+from dataclasses import dataclass
+
+ROUTE_SUBJECT = re.compile(r"^(\w+)\s+(/\S*)$")
+
+
+def normalize(path: str) -> str:
+    p = re.sub(r"\{[^}]*\}", "{}", path.strip())
+    p = re.sub(r"/{2,}", "/", p)
+    if len(p) > 1 and p.endswith("/"):
+        p = p[:-1]
+    return p or "/"
+
+
+def route_matches(pattern: str, route: str) -> bool:
+    """Whitelist-style match: leading slash optional, trailing '*' matches any depth, {} matches one segment."""
+    pat = normalize("/" + pattern.lstrip("/"))
+    rt = normalize(route)
+    if pat.endswith("/*"):
+        base = pat[:-2]
+        return rt == base or rt.startswith(base + "/")
+    if pat.endswith("*"):
+        return rt.startswith(pat[:-1])
+    ps, rs = pat.split("/"), rt.split("/")
+    if len(ps) != len(rs):
+        return False
+    return all(a == b or a == "{}" or b == "{}" or fnmatch.fnmatchcase(b, a) for a, b in zip(ps, rs))
+
+
+def edge_hits_route(edge_path: str, route: str) -> bool:
+    """Does a recorded call to edge_path reach route? A route parameter accepts any caller segment;
+    a caller parameter only matches a route parameter, never a literal segment."""
+    es, rs = normalize(edge_path).split("/"), normalize(route).split("/")
+    if len(es) != len(rs):
+        return False
+    for e, r in zip(es, rs):
+        if r == "{}":
+            continue
+        if e == "{}" or e != r:
+            return False
+    return True
+
+
+@dataclass
+class Gate:
+    verb: str
+    route: str
+    classification: str
+    file: str
+
+    @property
+    def exposed(self) -> bool:
+        return self.classification.startswith(("OPEN", "BLOCKED"))
+
+    @property
+    def pattern(self) -> str | None:
+        m = re.search(r"\bvia\s+(\S+)", self.classification)
+        return m.group(1) if m else None
+
+
+@dataclass
+class Caller:
+    repo: str
+    site: str
+    verb: str
+    path: str
+
+    def text(self) -> str:
+        return f"{self.repo} ({self.site}) {self.verb}".rstrip()
+
+
+class Store:
+    def __init__(self, path: str):
+        if not os.path.exists(path):
+            raise FileNotFoundError(path)
+        self.path = path
+        uri = f"file:{os.path.abspath(path)}?mode=ro"
+        self.db = sqlite3.connect(uri, uri=True)
+
+    def age_days(self) -> float:
+        return (time.time() - os.path.getmtime(self.path)) / 86400
+
+    def routes_in_file(self, repo: str, file: str) -> list[str]:
+        rows = self.db.execute(
+            "select subject from fact where repo=? and kind in ('route','route_gate') and (file=? or file like ?)",
+            (repo, file, f"%/{os.path.basename(file)}"),
+        ).fetchall()
+        out: list[str] = []
+        for (subj,) in rows:
+            m = ROUTE_SUBJECT.match(subj or "")
+            if m and m.group(2) not in out:
+                out.append(m.group(2))
+        return out
+
+    def gates(self, repo: str, route: str) -> list[Gate]:
+        rt = normalize(route)
+        out: list[Gate] = []
+        for subj, obj, file in self.db.execute(
+            "select subject, object, file from fact where repo=? and kind='route_gate'", (repo,)
+        ):
+            m = ROUTE_SUBJECT.match(subj or "")
+            if m and normalize(m.group(2)) == rt:
+                out.append(Gate(m.group(1), m.group(2), obj or "", file or ""))
+        return out
+
+    def whitelist_patterns(self, repo: str) -> list[tuple[str, bool]]:
+        """(pattern, authenticated) pairs seen in this repo's gate classifications."""
+        seen: dict[str, bool] = {}
+        for (obj,) in self.db.execute("select distinct object from fact where repo=? and kind='route_gate'", (repo,)):
+            m = re.search(r"\bvia\s+(\S+)", obj or "")
+            if m:
+                seen[m.group(1)] = not (obj or "").startswith("OPEN")
+        return sorted(seen.items())
+
+    def has_gate_data(self, repo: str) -> bool:
+        return (
+            self.db.execute("select 1 from fact where repo=? and kind='route_gate' limit 1", (repo,)).fetchone()
+            is not None
+        )
+
+    def callers(self, service: str, route: str) -> list[Caller]:
+        rt = normalize(route)
+        out: list[Caller] = []
+        for src_repo, src_site, dst_path, verb in self.db.execute(
+            "select src_repo, src_site, dst_path, coalesce(verb,'') from edge where dst_service=?", (service,)
+        ):
+            if dst_path and edge_hits_route(dst_path, rt):
+                out.append(Caller(src_repo or "?", src_site or "?", verb, dst_path or ""))
+        return out

gitvow_provider_facts-0.1.0/src/gitvow_provider_facts.egg-info/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: gitvow-provider-facts
+Version: 0.1.0
+Summary: gitvow provider answering gate questions from a derived fact store of routes, gates and callers.
+Author-email: Nikhil Bora <nikhil@wirevow.com>
+License: Apache-2.0
+Project-URL: Homepage, https://wirevow.dev/gitvow-provider-facts
+Project-URL: Repository, https://github.com/wirevow/gitvow-provider-facts
+Keywords: gitvow,provenance,policy,ai-agents,git
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: bandit[toml]>=1.7; extra == "dev"
+Requires-Dist: pip-audit>=2.7; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# gitvow-provider-facts
+
+A [gitvow](https://wirevow.dev/gitvow/) provider that answers the gate's questions from a derived fact store of your services: which routes exist, how each is gated, and who calls it.
+
+With it, an agent that adds an endpoint the authorization layer does not cover, or removes one that other services call, is stopped before the file changes, and the message names the whitelist pattern or the calling services.
+
+```sh
+pip install gitvow-provider-facts
+```
+
+```json
+"providers": [{
+  "name": "topology",
+  "command": "gitvow-provider-facts --store /var/lib/topology/facts.db --service orders",
+  "questions": ["route_gate", "route_callers", "gate_bearing"]
+}]
+```
+
+```
+$ gitvow ask route_callers /v1/orders --path src/api/OrdersResource.java
+topology: yes — called by client-orch (OrdersClient.java:88) POST; called by billing-worker (sync.py:41) GET; store built 2026-09-08 (1 day old)
+decision: CONFIRM
+```
+
+No runtime dependencies: Python 3.9+ and sqlite3 from the standard library. The provider holds no knowledge of its own; it reads a store you build. It never writes to the store and never contacts the network.
+
+Documentation: **https://wirevow.dev/gitvow-provider-facts/** · Protocol it implements: [gitvow provider protocol](https://wirevow.dev/gitvow/reference/provider-protocol/)
+
+Apache-2.0.

gitvow_provider_facts-0.1.0/src/gitvow_provider_facts.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/gitvow_provider_facts/__init__.py
+src/gitvow_provider_facts/cli.py
+src/gitvow_provider_facts/provider.py
+src/gitvow_provider_facts/store.py
+src/gitvow_provider_facts.egg-info/PKG-INFO
+src/gitvow_provider_facts.egg-info/SOURCES.txt
+src/gitvow_provider_facts.egg-info/dependency_links.txt
+src/gitvow_provider_facts.egg-info/entry_points.txt
+src/gitvow_provider_facts.egg-info/requires.txt
+src/gitvow_provider_facts.egg-info/top_level.txt
+tests/test_provider.py

gitvow_provider_facts-0.1.0/src/gitvow_provider_facts.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gitvow_provider_facts-0.1.0/src/gitvow_provider_facts.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gitvow-provider-facts = gitvow_provider_facts.cli:main

gitvow_provider_facts-0.1.0/src/gitvow_provider_facts.egg-info/requires.txt

@@ -0,0 +1,8 @@
+
+[dev]
+pytest>=8
+pytest-cov>=5
+ruff>=0.6
+bandit[toml]>=1.7
+pip-audit>=2.7
+mypy>=1.10

gitvow_provider_facts-0.1.0/src/gitvow_provider_facts.egg-info/top_level.txt

@@ -0,0 +1 @@
+gitvow_provider_facts

gitvow_provider_facts-0.1.0/tests/test_provider.py

@@ -0,0 +1,154 @@
+import json
+import os
+import subprocess
+import sys
+import time
+
+from gitvow_provider_facts.cli import main
+from gitvow_provider_facts.provider import Config, answer, resolve_route
+from gitvow_provider_facts.store import Store, edge_hits_route, normalize, route_matches
+from tests.conftest import F
+
+
+def test_normalize_and_matching():
+    assert normalize("/v1/orders/{id}/") == "/v1/orders/{}"
+    assert normalize("//a//b") == "/a/b"
+    assert route_matches("v1/webhook/*", "/v1/webhook/stripe/x")
+    assert route_matches("v1/webhook/*", "/v1/webhook")
+    assert not route_matches("v1/webhook/*", "/v1/webhooks")
+    assert route_matches("/v1/orders/{orderId}", "/v1/orders/{id}")
+    assert route_matches("/v1/orders/{id}", "/v1/orders/42")
+    assert not route_matches("/v1/orders", "/v1/orders/42")
+    assert edge_hits_route("/v1/orders/42", "/v1/orders/{id}")  # concrete call reaches the parameterised route
+    assert edge_hits_route("/v1/orders/{orderId}", "/v1/orders/{id}")
+    assert not edge_hits_route(
+        "/v1/orders/{orderId}", "/v1/orders/export"
+    )  # a caller of the id route is not a caller of export
+    assert not edge_hits_route("/v1/orders", "/v1/orders/{id}")
+
+
+def test_resolve_prefix_from_file(store):
+    st = Store(store)
+    assert resolve_route(st, "orders-svc", "/export", F) == (
+        "/v1/orders/export",
+        "prefix /v1/orders from OrdersResource.java",
+    )
+    assert resolve_route(st, "orders-svc", "/v1/orders/{id}", F) == ("/v1/orders/{}", "exact")
+    assert resolve_route(st, "orders-svc", "/v1/orders/export", F) == ("/v1/orders/export", "as written")
+    assert resolve_route(st, "orders-svc", "/export", "unknown.java") == ("/export", "as written")
+
+
+def cfg(store, **kw):
+    return Config(store, repo="orders-svc", service="orders", **kw)
+
+
+def test_route_gate_answers(store):
+    c = cfg(store)
+    r = answer(c, {"question": "route_gate", "subject": "/export", "path": F})
+    assert (
+        r["answer"] == "yes"
+        and "403" in " ".join(r["evidence"])
+        and "resolved to /v1/orders/export" in r["evidence"][0]
+    )
+    r = answer(c, {"question": "route_gate", "subject": "/{id}", "path": F})
+    assert r["answer"] == "no" and "reachable:AuthorizeV2" in r["evidence"][1]
+    r = answer(c, {"question": "route_gate", "subject": "/v1/webhook/new", "path": "controller/WebhookResource.java"})
+    assert r["answer"] == "yes" and "OPEN" in r["evidence"][1]
+    r = answer(c, {"question": "route_gate", "subject": "/myadmin/reports", "path": "controller/AdminResource.java"})
+    assert r["answer"] == "no" and "authenticated whitelist" in r["evidence"][1]
+    r = answer(c, {"question": "route_gate", "subject": "/v1/legacy/dump", "path": ""})
+    assert r["answer"] == "yes" and "BLOCKED" in r["evidence"][1]
+    r = answer(Config(store, repo="other-svc"), {"question": "route_gate", "subject": "/y", "path": "x.py"})
+    assert r["answer"] == "unknown" and "no gate classification" in r["evidence"][1]
+
+
+def test_route_callers(store):
+    c = cfg(store)
+    r = answer(c, {"question": "route_callers", "subject": "/v1/orders", "path": F})
+    assert r["answer"] == "yes" and any("client-orch (src/OrdersClient.java:88) POST" in e for e in r["evidence"])
+    assert not any("someone" in e for e in r["evidence"])  # different service
+    r = answer(c, {"question": "route_callers", "subject": "/{id}", "path": F})
+    assert r["answer"] == "yes" and any("billing-worker" in e for e in r["evidence"])
+    r = answer(c, {"question": "route_callers", "subject": "/v1/orders/export", "path": F})
+    assert r["answer"] == "unknown" and "no recorded callers" in r["evidence"][1]
+
+
+def test_gate_bearing_and_age(store):
+    c = cfg(store, gate_files=["auth/AuthorizeWhitelistedPaths.java", "deploy/values/production-*.yaml"])
+    assert (
+        answer(c, {"question": "gate_bearing", "subject": "x", "path": "svc/auth/AuthorizeWhitelistedPaths.java"})[
+            "answer"
+        ]
+        == "yes"
+    )
+    assert (
+        answer(c, {"question": "gate_bearing", "subject": "x", "path": "deploy/values/production-in.yaml"})["answer"]
+        == "yes"
+    )
+    assert answer(c, {"question": "gate_bearing", "subject": "x", "path": "README.md"})["answer"] == "no"
+    assert answer(cfg(store), {"question": "gate_bearing", "subject": "x", "path": "README.md"})["answer"] == "unknown"
+    old = time.time() - 40 * 86400
+    os.utime(store, (old, old))
+    r = answer(cfg(store), {"question": "route_callers", "subject": "/v1/orders", "path": F})
+    assert "STALE" in r["evidence"][-1] and "40 days ago" in r["evidence"][-1]
+    assert answer(c, {"question": "bogus", "subject": "x"})["answer"] == "unknown"
+
+
+def test_cli_stdin_and_ask(store, capsys, monkeypatch, tmp_path):
+    import io
+
+    monkeypatch.setattr(
+        "sys.stdin",
+        io.StringIO(
+            json.dumps(
+                {
+                    "protocol": 1,
+                    "question": "route_callers",
+                    "subject": "/v1/orders",
+                    "path": F,
+                    "repo": str(tmp_path / "orders-svc"),
+                }
+            )
+        ),
+    )
+    assert main(["--store", store, "--service", "orders"]) == 0
+    out = json.loads(capsys.readouterr().out)
+    assert out["answer"] == "yes"
+    assert main(["--store", store, "--repo", "orders-svc", "ask", "route_gate", "/export", "--path", F]) == 0
+    assert json.loads(capsys.readouterr().out)["answer"] == "yes"
+    assert main(["--store", "/nonexistent.db", "ask", "route_gate", "/x"]) == 3
+    monkeypatch.setattr("sys.stdin", io.StringIO("not json"))
+    assert main(["--store", store]) == 2
+
+
+def test_store_is_opened_read_only(store):
+    st = Store(store)
+    try:
+        st.db.execute("insert into fact(repo) values ('x')")
+        raise AssertionError("write should fail")
+    except Exception as e:
+        assert "readonly" in str(e).lower() or "read-only" in str(e).lower()
+
+
+def test_works_with_gitvow_as_subprocess(store, tmp_path):
+    """The real integration: gitvow's gate calls the console script and reads the answer."""
+    r = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "gitvow_provider_facts.cli",
+            "--store",
+            store,
+            "--service",
+            "orders",
+            "--repo",
+            "orders-svc",
+        ],
+        input=json.dumps(
+            {"protocol": 1, "question": "route_callers", "subject": "/v1/orders", "path": F, "repo": str(tmp_path)}
+        ),
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert json.loads(r.stdout)["answer"] == "yes"