toolgraph 0.0.1__py3-none-any.whl

toolgraph/graph/schema.py

@@ -0,0 +1,166 @@
+"""Graph schema: uniqueness constraints.
+
+Single-property uniqueness only — these work on Neo4j Community (node-key and
+composite-key constraints are Enterprise-only). Tools therefore carry a synthetic
+``key`` (``"<server>::<tool>"``) so identity is a single indexed property and
+MERGE stays idempotent. No vector index in this MVP.
+"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+from toolgraph.graph.driver import BackendConfigurationError, backend_name, session
+
+# Version of the physical backend schema this code understands. Bumped only
+# when a table/constraint shape changes incompatibly. IF NOT EXISTS silently
+# skips outdated tables, so without this gate an old database meets new code
+# only as confusing query-time errors.
+BACKEND_SCHEMA_VERSION = 1
+
+CONSTRAINTS: list[str] = [
+    "CREATE CONSTRAINT mcpserver_name IF NOT EXISTS FOR (s:MCPServer) REQUIRE s.name IS UNIQUE",
+    "CREATE CONSTRAINT tool_key IF NOT EXISTS FOR (t:Tool) REQUIRE t.key IS UNIQUE",
+    "CREATE CONSTRAINT resource_uri IF NOT EXISTS FOR (r:Resource) REQUIRE r.uri IS UNIQUE",
+    "CREATE CONSTRAINT agent_id IF NOT EXISTS FOR (a:Agent) REQUIRE a.id IS UNIQUE",
+    "CREATE CONSTRAINT policy_id IF NOT EXISTS FOR (p:Policy) REQUIRE p.id IS UNIQUE",
+    "CREATE CONSTRAINT exception_key IF NOT EXISTS FOR (e:ExpectedException) REQUIRE e.key IS UNIQUE",
+    "CREATE CONSTRAINT graphmeta_id IF NOT EXISTS FOR (m:GraphMeta) REQUIRE m.id IS UNIQUE",
+]
+
+# ADR-0004: run in the SAME transaction as every successful crawl load and
+# manifest ingest, so generation and graph state can never be observed out of
+# sync. It is an invalidation token, not a semantic version — a crawl of N
+# servers bumps N times. Rejected ingests return before reaching this.
+BUMP_GENERATION = (
+    "MERGE (m:GraphMeta {id:'singleton'}) "
+    "SET m.instance_id = coalesce(m.instance_id, $graph_instance_id), "
+    "m.generation = coalesce(m.generation, 0) + 1, m.updated_at = datetime()"
+)
+
+ENSURE_GRAPH_META = (
+    "MERGE (m:GraphMeta {id:'singleton'}) "
+    "SET m.instance_id = coalesce(m.instance_id, $graph_instance_id), "
+    "m.generation = coalesce(m.generation, 0)"
+)
+
+LADYBUG_SCHEMA: list[str] = [
+    "CREATE NODE TABLE IF NOT EXISTS MCPServer("
+    "name STRING PRIMARY KEY, version STRING, transport STRING, endpoint STRING, "
+    "last_crawled_at TIMESTAMP)",
+    "CREATE NODE TABLE IF NOT EXISTS Tool("
+    "key STRING PRIMARY KEY, name STRING, server STRING, description STRING, "
+    "input_schema STRING, read_only_hint BOOL, destructive_hint BOOL, "
+    "idempotent_hint BOOL, open_world_hint BOOL)",
+    "CREATE NODE TABLE IF NOT EXISTS Resource("
+    "uri STRING PRIMARY KEY, name STRING, mime_type STRING, description STRING)",
+    "CREATE NODE TABLE IF NOT EXISTS Agent(id STRING PRIMARY KEY)",
+    "CREATE NODE TABLE IF NOT EXISTS Policy("
+    "id STRING PRIMARY KEY, effect STRING, scope STRING, description STRING, "
+    "prov_source STRING, prov_confidence STRING, prov_evidence STRING)",
+    "CREATE NODE TABLE IF NOT EXISTS ExpectedException("
+    "key STRING PRIMARY KEY, agent STRING, tool_key STRING, resource STRING, "
+    "policy STRING, reason STRING)",
+    "CREATE NODE TABLE IF NOT EXISTS GraphMeta("
+    "id STRING PRIMARY KEY, instance_id STRING, generation INT64, updated_at TIMESTAMP, "
+    "governance_digest STRING, last_policy_change_id STRING, backend_schema_version INT64)",
+    "CREATE REL TABLE IF NOT EXISTS EXPOSES("
+    "FROM MCPServer TO Tool, source STRING, confidence STRING, evidence STRING)",
+    "CREATE REL TABLE IF NOT EXISTS PROVIDES("
+    "FROM MCPServer TO Resource, source STRING, confidence STRING, evidence STRING)",
+    "CREATE REL TABLE IF NOT EXISTS CAN_CALL("
+    "FROM Agent TO Tool, granted_by STRING, source STRING, confidence STRING, evidence STRING)",
+    "CREATE REL TABLE IF NOT EXISTS READS("
+    "FROM Tool TO Resource, source STRING, confidence STRING, evidence STRING)",
+    "CREATE REL TABLE IF NOT EXISTS WRITES("
+    "FROM Tool TO Resource, source STRING, confidence STRING, evidence STRING)",
+    "CREATE REL TABLE IF NOT EXISTS GOVERNED_BY("
+    "FROM Resource TO Policy, FROM Tool TO Policy, "
+    "source STRING, confidence STRING, evidence STRING)",
+]
+
+
+def exception_key(agent: str, tool_key: str, resource: str | None, policy: str) -> str:
+    """Collision-safe identity; null denotes an exception for any resource."""
+    from toolgraph.artifacts import canonical_json_bytes, sha256_bytes
+    from toolgraph.uris import normalize_resource_uri
+
+    resource = normalize_resource_uri(resource) if resource is not None else None
+    return "v2:" + sha256_bytes(canonical_json_bytes([agent, tool_key, resource, policy]))
+
+
+def tool_key(server_name: str, tool_name: str) -> str:
+    """Stable identity for a Tool node.
+
+    Components must not contain the delimiter: (server="a", tool="b::c") and
+    (server="a::b", tool="c") would otherwise collapse onto one key and MERGE
+    the same node. Model validation enforces this at the crawl boundary; this
+    check covers programmatic callers.
+    """
+    if "::" in server_name or "::" in tool_name:
+        raise ValueError(
+            "server and tool names must not contain '::' (the tool-key delimiter)"
+        )
+    return f"{server_name}::{tool_name}"
+
+
+def _stored_backend_schema_version(s) -> int | None:
+    try:
+        record = s.run(
+            "MATCH (m:GraphMeta {id:'singleton'}) "
+            "RETURN m.backend_schema_version AS version"
+        ).single()
+    except RuntimeError:
+        # Fresh embedded database: the GraphMeta table does not exist yet.
+        return None
+    return record["version"] if record else None
+
+
+def _refuse_version_mismatch(stored: int | None) -> None:
+    if stored is not None and stored != BACKEND_SCHEMA_VERSION:
+        raise BackendConfigurationError(
+            f"backend schema version {stored} does not match this build's "
+            f"{BACKEND_SCHEMA_VERSION} — "
+            + (
+                "upgrade toolgraph to a version that understands it"
+                if stored > BACKEND_SCHEMA_VERSION
+                else "migrate the database (no automatic migration exists)"
+            )
+        )
+
+
+def init_schema() -> None:
+    """Create all constraints (idempotent) and gate on the schema version."""
+    with session() as s:
+        # Gate BEFORE running any version-specific DDL: an incompatible client
+        # must not mutate the database on its way to the mismatch error.
+        _refuse_version_mismatch(_stored_backend_schema_version(s))
+        for stmt in LADYBUG_SCHEMA if backend_name() == "ladybug" else CONSTRAINTS:
+            s.run(stmt)
+        # Backfill databases created before the graph-state contract without
+        # invalidating caches: no authored or crawled graph fact changed.
+        s.run(ENSURE_GRAPH_META, graph_instance_id=str(uuid4()))
+        # Stamp without clobbering: coalesce keeps whatever version a
+        # concurrent initializer already wrote; every shipped database has the
+        # v1 shape, so a null stamp is always safe to fill.
+        s.run(
+            "MATCH (m:GraphMeta {id:'singleton'}) "
+            "SET m.backend_schema_version = "
+            "coalesce(m.backend_schema_version, $version)",
+            version=BACKEND_SCHEMA_VERSION,
+        )
+        # Re-read: if a different-version initializer won the coalesce race,
+        # refuse now instead of proceeding against its database.
+        _refuse_version_mismatch(_stored_backend_schema_version(s))
+
+
+def list_constraints() -> list[dict]:
+    if backend_name() == "ladybug":
+        return [{"name": statement.split("EXISTS", 1)[1].split("(", 1)[0].strip()}
+                for statement in LADYBUG_SCHEMA]
+    with session() as s:
+        return [dict(r) for r in s.run("SHOW CONSTRAINTS")]
+
+
+def bump_generation(tx) -> None:
+    tx.run(BUMP_GENERATION, graph_instance_id=str(uuid4()))

toolgraph/graph/selector.py

@@ -0,0 +1,423 @@
+"""Deterministic selector surface (ADR-0005): filter/features in, learning out.
+
+Three batch-first entry points serve tool selection as a context-engineering
+layer — shrink a candidate catalog deterministically before any relevance
+ranker sees it:
+
+- ``rank_features`` — per-candidate facts + a rule-based ``risk_score`` from
+  the published fixed table below. No relevance, no learning.
+- ``eligible_tools`` — hard filter with reject reasons and policy-evidence
+  paths. Profiles are named rule sets, not learned thresholds; production
+  default is ``strict``.
+- ``selection_explain`` — compact human-readable reasons for one (agent, tool).
+
+Batch-first because per-candidate ``check_access`` calls scale linearly with
+candidate count — unacceptable on the online selection path. Everything here
+runs a fixed number of queries regardless of N.
+
+Hard boundary (ADR-0005): no relevance scoring, no learning. A learned
+consumer may never override a hard reject (NOT_GRANTED, violation, drifted).
+"""
+
+from __future__ import annotations
+
+from toolgraph.graph.driver import session
+from toolgraph.graph.queries import _deny_evidence_batch, agent_exists, resolve_tool_refs
+
+# Hard-filter rule sets (ADR-0005). Reasons are checked in _REASON_PRECEDENCE
+# order; the first applicable reason that the profile rejects wins. These are
+# named rule sets, NOT tunable thresholds — changing them is an ADR-level
+# decision, not a config knob.
+#
+# - strict (production default): only a clean, fully-authored ALLOW passes —
+#   granted, no DENY path of any classification, currently exposed, and with
+#   authored data-flow (an unmapped tool is exactly the blind spot the graph
+#   cannot vouch for, so production fails closed).
+# - review (human-in-the-loop): operator-declared exceptions and unmapped
+#   tools pass; violations still reject.
+# - explore (offline eval / sandbox): only resolution failures, missing
+#   grants, and drift reject — DENY rows become penalties via rank_features.
+PROFILES: dict[str, frozenset[str]] = {
+    "strict": frozenset(
+        {
+            "TOOL_NOT_FOUND",
+            "AMBIGUOUS_TOOL",
+            "NOT_GRANTED",
+            "DENY_VIOLATION",
+            "DENY_GOVERNED",
+            "DRIFTED",
+            "UNMAPPED",
+        }
+    ),
+    "review": frozenset(
+        {"TOOL_NOT_FOUND", "AMBIGUOUS_TOOL", "NOT_GRANTED", "DENY_VIOLATION", "DRIFTED"}
+    ),
+    "explore": frozenset({"TOOL_NOT_FOUND", "AMBIGUOUS_TOOL", "NOT_GRANTED", "DRIFTED"}),
+}
+
+DEFAULT_PROFILE = "strict"
+
+# Batch bound, mirroring the control-plan limit: the selector is batch-first,
+# but an unbounded candidate list still UNWINDs as one query parameter. Lives
+# here so every surface — CLI, MCP server, library callers — is bounded.
+MAX_CANDIDATES = 4096
+
+# Drift rejects in EVERY profile (the report's regression criteria): a tool no
+# server currently exposes cannot be called, so passing it is never useful.
+_REASON_PRECEDENCE = (
+    "TOOL_NOT_FOUND",
+    "AMBIGUOUS_TOOL",
+    "NOT_GRANTED",
+    "DENY_VIOLATION",
+    "DENY_GOVERNED",
+    "DRIFTED",
+    "UNMAPPED",
+)
+
+
+def _risk_score(feature: dict) -> float | None:
+    """Rule-based risk from the published fixed table (ADR-0005 / report).
+
+    First match wins, top-down. This is a fact-derived feature, not a learned
+    weight — consumers may add penalties on top but never subtract a hard
+    reject. ``None`` when the candidate didn't resolve to exactly one tool
+    (no facts to score).
+
+        1.0  DENY path with classification=violation
+        0.8  drifted (no live EXPOSES edge)
+        0.6  unmapped (no authored READS/WRITES)
+        0.4  unbacked load-bearing edge in the tool's evidence chain
+        0.2  DENY path fully covered by operator-declared exceptions
+        0.0  otherwise
+    """
+    if not feature["found"] or feature["ambiguous"]:
+        return None
+    if feature["classification"] == "violation":
+        return 1.0
+    if feature["is_drifted"]:
+        return 0.8
+    if feature["is_unmapped"]:
+        return 0.6
+    if feature["has_unbacked_edges"]:
+        return 0.4
+    if feature["classification"] == "authorized_but_governed":
+        return 0.2
+    return 0.0
+
+
+def _resolve_all(s, refs: list[str]) -> dict[str, list[str]]:
+    """Use the same bounded resolution as ingest and single-tool queries."""
+    return resolve_tool_refs(s, refs)
+
+
+def _tool_facts(s, keys: list[str], agent: str) -> dict[str, dict]:
+    """Batch per-tool facts for resolved keys: grant, drift, mapping, evidence
+    coverage, and the #14 annotation self-claims (which enrich features but
+    never gate by themselves — they are crawled/medium claims, ADR-0006)."""
+    rows = s.run(
+        """
+        MATCH (t:Tool) WHERE t.key IN $keys
+        RETURN t.key AS key,
+               t.name AS name, t.server AS server,
+               t.read_only_hint AS read_only_hint,
+               t.destructive_hint AS destructive_hint,
+               t.idempotent_hint AS idempotent_hint,
+               t.open_world_hint AS open_world_hint,
+               EXISTS { MATCH (:Agent {id:$agent})-[:CAN_CALL]->(t) } AS permitted,
+               NOT EXISTS { MATCH (:MCPServer)-[:EXPOSES]->(t) } AS is_drifted,
+               NOT EXISTS { MATCH (t)-[:READS|WRITES]->(:Resource) } AS is_unmapped,
+               EXISTS {
+                   MATCH (t)-[r:READS|WRITES|GOVERNED_BY]->()
+                   WHERE r.evidence IS NULL OR trim(r.evidence) = ''
+               } OR EXISTS {
+                   MATCH (t)-[:READS|WRITES]->(:Resource)-[g:GOVERNED_BY]->()
+                   WHERE g.evidence IS NULL OR trim(g.evidence) = ''
+               } AS has_unbacked_edges
+        """,
+        keys=keys,
+        agent=agent,
+    )
+    return {r["key"]: dict(r) for r in rows}
+
+
+def _classify(deny_rows: list[dict]) -> str | None:
+    """Worst-case classification across a tool's deny paths: any violation row
+    dominates; all-exception rows collapse to authorized_but_governed."""
+    if not deny_rows:
+        return None
+    if any(d.get("classification") == "violation" for d in deny_rows):
+        return "violation"
+    return "authorized_but_governed"
+
+
+def rank_features(agent: str, candidates: list[str]) -> dict:
+    """Batch selection features for every candidate, in input order.
+
+    ``agent_found: false`` means selection itself should abort (a context
+    construction error, not an empty result) — features come back empty.
+
+    Each feature row keeps the input ref as its stable id (``candidate``) and
+    carries: resolution (found/ambiguous/tool_key), grant (``permitted``),
+    verdict (mirrors ``check_access``), worst-case deny ``classification``
+    with the full ``deny_paths``, drift / mapping / evidence-coverage facts,
+    the four annotation self-claims (ADR-0006), and the rule-based
+    ``risk_score`` (see ``_risk_score`` for the fixed table).
+    """
+    if len(candidates) > MAX_CANDIDATES:
+        raise ValueError(
+            f"{len(candidates)} candidates exceed the {MAX_CANDIDATES} limit"
+        )
+    if not agent_exists(agent):
+        return {"agent": agent, "agent_found": False, "features": []}
+
+    with session() as s:
+        resolved = _resolve_all(s, candidates)
+        unique_keys = sorted(
+            {keys[0] for keys in resolved.values() if len(keys) == 1}
+        )
+        facts = _tool_facts(s, unique_keys, agent)
+        deny = _deny_evidence_batch(s, unique_keys, agent=agent)
+
+    features: list[dict] = []
+    for ref in candidates:  # input order is the contract — never re-sorted
+        keys = resolved.get(ref, [])
+        row: dict = {
+            "candidate": ref,
+            "tool_key": None,
+            "found": bool(keys),
+            "ambiguous": len(keys) > 1,
+            "permitted": None,
+            "verdict": None,
+            "classification": None,
+            "deny_paths": [],
+            "is_drifted": None,
+            "is_unmapped": None,
+            "has_unbacked_edges": None,
+            "read_only_hint": None,
+            "destructive_hint": None,
+            "idempotent_hint": None,
+            "open_world_hint": None,
+        }
+        if not keys:
+            row["verdict"] = "TOOL_NOT_FOUND"
+        elif len(keys) > 1:
+            # Never auto-resolved: the consumer must re-submit the
+            # server-qualified key (regression criterion #1).
+            row["verdict"] = "AMBIGUOUS_TOOL"
+            row["candidates"] = keys
+        elif keys[0] not in facts:
+            # Tool deleted between resolution and the facts read — Neo4j is
+            # read-committed, so the two batch queries can straddle a
+            # concurrent crawl/ingest (the same window check_access closes
+            # with its meta-is-None branch). Report the truth signal instead
+            # of crashing the whole batch (Codex review).
+            row["found"] = False
+            row["verdict"] = "TOOL_NOT_FOUND"
+        else:
+            key = keys[0]
+            f = facts[key]
+            deny_rows = deny[key]
+            row["tool_key"] = key
+            row["permitted"] = f["permitted"]
+            row["classification"] = _classify(deny_rows)
+            row["deny_paths"] = deny_rows
+            row["is_drifted"] = f["is_drifted"]
+            row["is_unmapped"] = f["is_unmapped"]
+            row["has_unbacked_edges"] = f["has_unbacked_edges"]
+            for hint in (
+                "read_only_hint",
+                "destructive_hint",
+                "idempotent_hint",
+                "open_world_hint",
+            ):
+                row[hint] = f[hint]
+            if not f["permitted"]:
+                row["verdict"] = "NOT_GRANTED"
+            elif deny_rows:
+                row["verdict"] = "DENY"
+            else:
+                row["verdict"] = "ALLOW"
+        row["risk_score"] = _risk_score(row)
+        features.append(row)
+
+    return {"agent": agent, "agent_found": True, "features": features}
+
+
+def _applicable_reasons(feature: dict) -> list[str]:
+    """All reject conditions this feature row triggers, in precedence order."""
+    reasons: list[str] = []
+    if not feature["found"]:
+        reasons.append("TOOL_NOT_FOUND")
+        return reasons  # nothing else is knowable about an unresolved ref
+    if feature["ambiguous"]:
+        reasons.append("AMBIGUOUS_TOOL")
+        return reasons
+    if not feature["permitted"]:
+        reasons.append("NOT_GRANTED")
+    if feature["classification"] == "violation":
+        reasons.append("DENY_VIOLATION")
+    elif feature["classification"] == "authorized_but_governed":
+        reasons.append("DENY_GOVERNED")
+    if feature["is_drifted"]:
+        reasons.append("DRIFTED")
+    if feature["is_unmapped"]:
+        reasons.append("UNMAPPED")
+    return reasons
+
+
+def filter_features(ranked: dict, profile: str = DEFAULT_PROFILE) -> dict:
+    """Pure hard filter over an already-computed ``rank_features`` result.
+
+    Runs no queries: producers that need both the filter verdict and the
+    feature rows (policy bundle, preflight ``--features``, explain) call
+    ``rank_features`` once and filter its output, instead of paying the full
+    graph evaluation twice inside the generation-retry bracket.
+    """
+    if profile not in PROFILES:
+        raise ValueError(
+            f"unknown profile {profile!r} — expected one of {sorted(PROFILES)}"
+        )
+    agent = ranked["agent"]
+    if not ranked["agent_found"]:
+        return {
+            "agent": agent,
+            "agent_found": False,
+            "profile": profile,
+            "eligible": [],
+            "rejected": [],
+        }
+
+    rejects = PROFILES[profile]
+    eligible: list[str] = []
+    rejected: list[dict] = []
+    for feature in ranked["features"]:
+        reason = next(
+            (r for r in _applicable_reasons(feature) if r in rejects), None
+        )
+        if reason is None:
+            eligible.append(feature["tool_key"])
+            continue
+        row = {
+            "candidate": feature["candidate"],
+            "tool_key": feature["tool_key"],
+            "reason": reason,
+        }
+        if reason == "AMBIGUOUS_TOOL":
+            row["candidates"] = feature["candidates"]
+        if reason in ("DENY_VIOLATION", "DENY_GOVERNED"):
+            wanted = (
+                "violation" if reason == "DENY_VIOLATION" else "authorized_but_governed"
+            )
+            row["paths"] = [
+                d["path"]
+                for d in feature["deny_paths"]
+                if d.get("classification") == wanted
+            ]
+        rejected.append(row)
+
+    return {
+        "agent": agent,
+        "agent_found": True,
+        "profile": profile,
+        "eligible": eligible,
+        "rejected": rejected,
+    }
+
+
+def eligible_tools(
+    agent: str, candidates: list[str], profile: str = DEFAULT_PROFILE
+) -> dict:
+    """Hard filter with reject reasons and policy-evidence paths (ADR-0005).
+
+    ``eligible`` holds resolved tool keys in candidate input order; every
+    rejected row keeps the input ref (``candidate``), the winning ``reason``
+    (first by precedence among the profile's reject set), and — for DENY
+    reasons — the graph paths that prove it. A learned consumer may rerank
+    ``eligible`` but may never resurrect a rejected row.
+    """
+    if profile not in PROFILES:
+        raise ValueError(
+            f"unknown profile {profile!r} — expected one of {sorted(PROFILES)}"
+        )
+    return filter_features(rank_features(agent, candidates), profile)
+
+
+def selection_explain(
+    agent: str, tool: str, profile: str = DEFAULT_PROFILE
+) -> dict:
+    """Compact human-readable reasons for one (agent, tool) — a view over the
+    same facts ``rank_features`` returns, for operators and end users."""
+    if profile not in PROFILES:
+        raise ValueError(
+            f"unknown profile {profile!r} — expected one of {sorted(PROFILES)}"
+        )
+    ranked = rank_features(agent, [tool])
+    if not ranked["agent_found"]:
+        return {
+            "agent": agent,
+            "tool": tool,
+            "tool_key": None,
+            "agent_found": False,
+            "profile": profile,
+            "decision": "rejected",
+            "reasons": [f"agent {agent!r} not found in the graph — selection aborted"],
+        }
+
+    feature = ranked["features"][0]
+    filtered = filter_features(ranked, profile)
+    decision = "eligible" if filtered["eligible"] else "rejected"
+
+    reasons: list[str] = []
+    if not feature["found"]:
+        reasons.append(f"no tool named {tool!r} in the graph")
+    elif feature["ambiguous"]:
+        reasons.append(
+            f"bare name matches multiple servers {feature['candidates']} — "
+            f"pass the server-qualified key; never auto-selected"
+        )
+    else:
+        reasons.append(
+            "agent has CAN_CALL grant"
+            if feature["permitted"]
+            else "agent has no CAN_CALL grant"
+        )
+        if not feature["deny_paths"]:
+            reasons.append("no DENY policy path found")
+        for d in feature["deny_paths"]:
+            label = d.get("classification", "deny")
+            line = f"DENY path [{label}]: {d['path']}"
+            if d.get("exception_reason"):
+                line += f" (operator: {d['exception_reason']})"
+            reasons.append(line)
+        reasons.append(
+            "tool has drifted: no server currently exposes it"
+            if feature["is_drifted"]
+            else "tool is currently exposed by a crawled server"
+        )
+        reasons.append(
+            "no authored READS/WRITES — data-flow effects unclassified"
+            if feature["is_unmapped"]
+            else "data-flow effects are authored (READS/WRITES present)"
+        )
+        reasons.append(
+            "load-bearing edge(s) missing evidence pointers"
+            if feature["has_unbacked_edges"]
+            else "all load-bearing edges carry evidence"
+        )
+        for hint in ("read_only_hint", "destructive_hint", "idempotent_hint", "open_world_hint"):
+            if feature[hint] is not None:
+                reasons.append(
+                    f"server self-claim (crawled/medium): {hint}={feature[hint]}"
+                )
+
+    return {
+        "agent": agent,
+        "tool": tool,
+        "tool_key": feature["tool_key"],
+        "agent_found": True,
+        "found": feature["found"],
+        "profile": profile,
+        "decision": decision,
+        "risk_score": feature["risk_score"],
+        "reasons": reasons,
+    }

toolgraph/graph/store.py

@@ -0,0 +1,57 @@
+"""Domain-level graph ports used by policy services.
+
+No Cypher or backend result object crosses this boundary. The current runtime
+implementation delegates to the established query/selector services; backend
+adapters remain responsible for DDL, transactions, and row normalization.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from toolgraph.graph import queries, selector
+
+
+class GraphReader(Protocol):
+    def state(self) -> queries.GraphState: ...
+
+    def exposed_tool_contracts(self) -> list[dict]: ...
+
+    def eligible_tools(self, agent: str, candidates: list[str], profile: str) -> dict: ...
+
+    def rank_features(self, agent: str, candidates: list[str]) -> dict: ...
+
+
+class EvaluatingGraphReader(GraphReader, Protocol):
+    # Optional: adapters that can evaluate once and filter in memory expose
+    # this combined form; build_policy_bundle prefers it and falls back to the
+    # eligible_tools + rank_features pair for adapters that do not.
+    def evaluate(self, agent: str, candidates: list[str], profile: str) -> dict: ...
+
+
+class RuntimeGraphStore:
+    """Backend-neutral policy read service over the configured graph adapter."""
+
+    def state(self) -> queries.GraphState:
+        return queries.graph_state()
+
+    def exposed_tool_contracts(self) -> list[dict]:
+        return queries.exposed_tool_contracts()
+
+    def eligible_tools(self, agent: str, candidates: list[str], profile: str) -> dict:
+        return selector.eligible_tools(agent, candidates, profile=profile)
+
+    def rank_features(self, agent: str, candidates: list[str]) -> dict:
+        return selector.rank_features(agent, candidates)
+
+    def evaluate(self, agent: str, candidates: list[str], profile: str) -> dict:
+        """One graph evaluation; the hard filter is pure over the ranked rows."""
+        ranked = selector.rank_features(agent, candidates)
+        if not ranked["agent_found"]:
+            return {"agent_found": False, "features": [], "filtered": None}
+        filtered = selector.filter_features(ranked, profile)
+        return {
+            "agent_found": True,
+            "features": ranked["features"],
+            "filtered": filtered,
+        }