arbiter-engine 0.1.0__py3-none-any.whl

arbiter_engine/mcp/__init__.py

@@ -0,0 +1 @@
+"""arbiter-engine v0.1 — arbiter_engine/mcp."""

arbiter_engine/mcp/server.py

@@ -0,0 +1,221 @@
+"""The MCP transport shim.
+
+Deliberately thin. All five tools live in :mod:`arbiter_engine.api`
+as plain functions over the engine (moved there, because they are
+engine API rather than transport); this module only registers them with the SDK and
+serialises the envelope. Everything worth testing is testable without
+importing ``mcp`` at all, which is why the tool tests need no protocol
+round-trip.
+
+The SDK import is **lazy**, inside :func:`build_server`. Importing this module
+must not require ``mcp`` to be installed — the engine is the dependency, the
+transport is not (the scope ruling holds the platform; the server
+holds neither).
+
+Run with:
+
+    python3 -m arbiter_engine.mcp.server
+
+(Inside the orchestrator repo the same module runs at its in-repo path, from
+the repo parent on the path. That path is deliberately not spelled out here.)
+
+This module now SHIPS -- the public-API ruling decided the
+surface is a permanent public contract -- so its own docstring is public text. It previously gave only
+the in-repo invocation, with an absolute operator path in front of it: a private
+package name and a private filesystem path, both in a docstring, where the
+build's stray scan cannot see them because that scan matches import STATEMENTS
+and this is prose. Name what a reader actually has, and nothing else.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List
+
+from arbiter_engine.api import (
+    EngineSession, attest, check, gaps, model_describe, traverse,
+)
+
+#: The five primitives, in the order an internal ruling lists them. Each entry is the
+#: name, a one-line description for the client, and the JSON-Schema input.
+TOOL_SPECS: List[Dict[str, Any]] = [
+    {
+        "name": "model_describe",
+        "description": (
+            "What domain model is loaded: entity types, indicators, and the "
+            "axioms each indicator DECLARES. Call this before reasoning — it "
+            "is the vocabulary, and an entity type absent from it does not "
+            "exist in this model. Declared is not the same as evaluated."
+        ),
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "check",
+        "description": (
+            "Evaluate the declared invariants over the supplied observations. "
+            "Returns findings AND what could not be evaluated, with reasons — "
+            "an empty findings list with a populated not_checked list means "
+            "nothing was measured, not that nothing is wrong."
+        ),
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "traverse",
+        "description": (
+            "Walk the entity graph. One primitive subsumes root-cause "
+            "(direction=reverse), impact (forward), and what-if "
+            "(value_mode=hypothetical with overrides)."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "start_nodes": {"type": "array", "items": {"type": "string"}},
+                "direction": {
+                    "type": "string",
+                    "enum": ["forward", "reverse", "bidirectional"],
+                },
+                # An internal ruling fed PROJECTED (2026-08-04), so the enum offers it.
+                # It was withheld while the mode was inert; advertising a
+                # capability nothing implements is the shape, and so
+                # is leaving a withholding note whose stated reason has since
+                # been resolved.
+                "value_mode": {
+                    "type": "string",
+                    "enum": ["current", "hypothetical", "projected"],
+                },
+                "max_hops": {"type": "integer"},
+                "overrides": {"type": "object"},
+            },
+            "required": ["start_nodes"],
+        },
+    },
+    {
+        "name": "gaps",
+        "description": (
+            "What the model is missing, as priority-ranked questions. This is "
+            "what the engine needs to know next in order to answer better."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {"start_node": {"type": "string"}},
+        },
+    },
+    {
+        "name": "attest",
+        "description": (
+            "The evidence behind a finding: which axiom, which threshold, how "
+            "many observations. Engine-side evidence only."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "problem_type": {"type": "string"},
+                "entity_id": {"type": "string"},
+            },
+            "required": ["problem_type"],
+        },
+    },
+]
+
+_HANDLERS = {
+    "model_describe": lambda s, a: model_describe(s),
+    "check": lambda s, a: check(s),
+    "traverse": lambda s, a: traverse(
+        s, a["start_nodes"], a.get("direction", "forward"),
+        a.get("value_mode", "current"), a.get("max_hops", 4),
+        a.get("overrides")),
+    "gaps": lambda s, a: gaps(s, a.get("start_node")),
+    "attest": lambda s, a: attest(s, a["problem_type"], a.get("entity_id")),
+}
+
+
+def dispatch(session: EngineSession, name: str,
+             arguments: Dict[str, Any]) -> Dict[str, Any]:
+    """Route one tool call and return the envelope as a dict.
+
+    Kept separate from the SDK registration so the routing table itself is
+    testable — a name present in TOOL_SPECS but missing from _HANDLERS is the
+    kind of gap that otherwise surfaces only at runtime.
+    """
+    handler = _HANDLERS.get(name)
+    if handler is None:
+        raise KeyError(f"unknown tool: {name}")
+    return handler(session, arguments or {}).to_dict()
+
+
+def build_server(session: EngineSession | None = None):
+    """Construct the MCP server. Imports the SDK lazily.
+
+    this targets ``mcp.server.MCPServer``, the high-level class in
+    the 2.x SDK, which derives each tool's input schema from the wrapper's
+    signature. The first version registered handlers with
+    ``@server.list_tools()`` / ``@server.call_tool()`` on the low-level
+    ``Server``; those decorators do not exist in 2.x, so **it raised
+    ``AttributeError`` on the first line of registration and had never once
+    been run.** Nothing caught it because the SDK cannot be installed in this
+    repo's environment, so the shim had no test at all — see the module note
+    below.
+
+    The wrappers are deliberately trivial: each one calls :func:`dispatch`,
+    which stays the single routing table and stays testable without the SDK.
+    ``TOOL_SPECS`` remains the source of the descriptions, because those are
+    what an agent actually reads.
+    """
+    from mcp.server import MCPServer  # noqa: PLC0415 — deliberate lazy import
+
+    state = session or EngineSession()
+    server = MCPServer("arbiter-engine")
+    spec_by_name = {spec["name"]: spec for spec in TOOL_SPECS}
+
+    def _emit(name: str, arguments: Dict[str, Any]) -> str:
+        return json.dumps(dispatch(state, name, arguments), indent=2)
+
+    async def model_describe_tool() -> str:
+        return _emit("model_describe", {})
+
+    async def check_tool() -> str:
+        return _emit("check", {})
+
+    async def traverse_tool(
+        start_nodes: List[str],
+        direction: str = "forward",
+        value_mode: str = "current",
+        max_hops: int = 4,
+        overrides: Dict[str, Any] | None = None,
+    ) -> str:
+        return _emit("traverse", {
+            "start_nodes": start_nodes, "direction": direction,
+            "value_mode": value_mode, "max_hops": max_hops,
+            "overrides": overrides,
+        })
+
+    async def gaps_tool(start_node: str | None = None) -> str:
+        return _emit("gaps", {"start_node": start_node})
+
+    async def attest_tool(problem_type: str,
+                          entity_id: str | None = None) -> str:
+        return _emit("attest", {"problem_type": problem_type,
+                                "entity_id": entity_id})
+
+    for name, fn in (
+        ("model_describe", model_describe_tool),
+        ("check", check_tool),
+        ("traverse", traverse_tool),
+        ("gaps", gaps_tool),
+        ("attest", attest_tool),
+    ):
+        server.add_tool(fn, name=name,
+                        description=spec_by_name[name]["description"])
+
+    return server
+
+
+def main() -> int:
+    import asyncio
+
+    asyncio.run(build_server().run_stdio_async())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

arbiter_engine/ontology/__init__.py

@@ -0,0 +1,18 @@
+"""
+Ontology Reasoning - Layer 2 Detection.
+
+The ontology layer uses semantic reasoning based on health indicators
+defined in RDF/OWL ontologies. It maps entities to health concepts
+and checks the 6 System Health Axioms.
+
+Key Features:
+- RDF/TTL ontology support via rdflib
+- Health meta-ontology for domain-agnostic concepts
+- Per-axiom reasoning with configurable thresholds
+- History-aware detection for temporal axioms
+"""
+
+from .reasoner import UnifiedAxiomReasoner
+from .loader import OntologyLoader
+
+__all__ = ['UnifiedAxiomReasoner', 'OntologyLoader']

arbiter_engine/ontology/axiom_verdicts_production.py

@@ -0,0 +1,332 @@
+"""AxiomVerdict production-readiness substrate (chain head).
+
+Production-readiness substrate for the 8 canonical axiom checkers at
+arbiter_engine/ontology/axioms/ (HOMEOSTASIS / RESPONSIVENESS / MONOTONICITY /
+BOUNDEDNESS / CONSISTENCY / CONSERVATION / CAUSALITY / PREDICTION_QUALITY).
+
+Per sibling-within-module precedent: axioms/ dir hosts 8
+sibling checker modules with no single shared parent module suitable for
+sibling extension. ships substrate at new standalone module
+(parent = `arbiter_engine/ontology/`, sibling to `axioms/` package) rather
+than mutate any individual checker. the established pattern sibling-substrate
+discipline preserved (substrate sibling at axis-parent level rather than
+single-module level).
+
+Adds per-verdict production recording + 5 production-readiness public
+functions + an established pattern env-gate. Composes hybrid
+emit-policy decision (transition OR confidence_threshold gate) +
+attestation severity floor + NaturalCategoryDispatcher
+(emit_policy axis dispatch via existing 9th canonical axis added; no new axis).
+
+the established pattern sibling-substrate-within-existing-module variant.
+
+Domain-agnostic: axiom_name + entity_id + verdict + confidence scalars
+opaque; no per-domain dispatch.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Dict, Iterator, List, Optional
+
+
+def _env_bool(name: str, default: bool = False) -> bool:
+    raw = os.environ.get(name, "1" if default else "0").strip().lower()
+    return raw in ("1", "true", "yes", "on")
+
+
+DT_AXIOM_VERDICT_PRODUCTION_ENABLED: bool = _env_bool(
+    "DT_AXIOM_VERDICT_PRODUCTION_ENABLED", default=False
+)
+DT_AXIOM_VERDICT_PRODUCTION_RING_CAP: int = int(
+    os.environ.get("DT_AXIOM_VERDICT_PRODUCTION_RING_CAP", "10000")
+)
+DT_AXIOM_VERDICT_CONFIDENCE_THRESHOLD: float = float(
+    os.environ.get("DT_AXIOM_VERDICT_CONFIDENCE_THRESHOLD", "0.5")
+)
+
+# Per hybrid emit-policy default
+PRODUCTION_AXIOM_VERDICT_EMIT_POLICY_HYBRID: str = "hybrid"
+PRODUCTION_AXIOM_VERDICT_EMIT_POLICY_FULL_EMIT: str = "full_emit"
+PRODUCTION_AXIOM_VERDICT_EMIT_POLICY_SUPPRESSED: str = "suppressed"
+KNOWN_PRODUCTION_AXIOM_VERDICT_EMIT_POLICIES = frozenset([
+    PRODUCTION_AXIOM_VERDICT_EMIT_POLICY_HYBRID,
+    PRODUCTION_AXIOM_VERDICT_EMIT_POLICY_FULL_EMIT,
+    PRODUCTION_AXIOM_VERDICT_EMIT_POLICY_SUPPRESSED,
+])
+DEFAULT_PRODUCTION_AXIOM_VERDICT_EMIT_POLICY: str = (
+    PRODUCTION_AXIOM_VERDICT_EMIT_POLICY_HYBRID
+)
+
+# The 8 canonical axiom names per arbiter_engine/ontology/axioms/*.py
+KNOWN_CANONICAL_AXIOMS = frozenset([
+    "HOMEOSTASIS",
+    "RESPONSIVENESS",
+    "MONOTONICITY",
+    "BOUNDEDNESS",
+    "CONSISTENCY",
+    "CONSERVATION",
+    "CAUSALITY",
+    "PREDICTION_QUALITY",
+])
+
+
+@dataclass(frozen=True)
+class ProductionAxiomVerdict:
+    """ per-verdict production-readiness axiom-verdict event.
+
+    5 opaque fields domain-agnostic invariant. Frozen for
+    audit-trail provenance emit-policy decision.
+
+     (Bucket A; 2nd worked example after RCA):
+    added optional ``cluster_id`` for per-axis cluster-scope filtering.
+    Default None preserves previously behavior; emission callsites that
+    pass cluster_id stamp the record so
+    ``get_axiom_verdicts(cluster_id=X)`` can filter. Field added with
+    default so existing emissions are backward-compat.
+    """
+
+    axiom_name: str
+    entity_id: str
+    verdict: str  # "PASS" | "FAIL" | "UNKNOWN"
+    confidence: float
+    emit_policy_per_cd1098: str
+    cluster_id: Optional[str] = None  # (Bucket A)
+
+
+def resolve_production_axiom_verdict_emit_policy(value: Optional[str]) -> str:
+    """Safe-default to hybrid."""
+    if value is None or value not in KNOWN_PRODUCTION_AXIOM_VERDICT_EMIT_POLICIES:
+        return DEFAULT_PRODUCTION_AXIOM_VERDICT_EMIT_POLICY
+    return value
+
+
+_PRODUCTION_VERDICTS: List[ProductionAxiomVerdict] = []
+_PRODUCTION_LOCK = threading.RLock()
+_PRODUCTION_LAST_VERDICT: Dict[tuple, str] = {}  # (entity_id, axiom_name) -> verdict
+
+
+# ---------- Layer 3 ContextVar emission-scope stamping ----------
+#
+# `record_axiom_verdict` is called from `arbiter_engine/ontology/reasoner.py`
+# inside the per-axiom check loop. That code path does NOT know cluster_id
+# at the function-signature level — DetectorInterface.detect() takes
+# (entities, graph, history) without cluster_id, and threading cluster_id
+# through the detector interface chain is out-of-scope (would touch every
+# detector implementation).
+#
+# Instead, callers in the full system (live loop + Monte Carlo path) wrap
+# the detect-call with `cluster_scope(cluster_id)`; the ContextVar
+# propagates correctly through async/await chains (asyncio.create_task
+# copies the context by default). Inside `record_axiom_verdict`, if the
+# explicit `cluster_id` parameter is None, we fall back to reading the
+# ContextVar. This is minimal-invasive Layer-3 stamping without rewriting
+# the detector contract.
+#
+# substrate-callsite-gap discipline (post-promotion to
+# reference architecture): the substrate-side ContextVar +
+# the caller-side `with cluster_scope(cluster_id):` block together form
+# the bridge between substrate-emission and cluster-aware caller context.
+_CURRENT_CLUSTER_ID: ContextVar[Optional[str]] = ContextVar(
+    "axiom_verdict_cluster_id", default=None,
+)
+
+
+@contextmanager
+def cluster_scope(cluster_id: Optional[str]) -> Iterator[None]:
+    """ Layer 3 helper: wrap a detect-call so emissions stamp
+    cluster_id automatically.
+
+    Usage in the full system:
+
+        with cluster_scope(cluster_id):
+            detection_result = await bridge.detect(entities, graph)
+
+    Any `record_axiom_verdict()` calls inside the block — including those
+    several frames deep in the detector chain — will pick up cluster_id
+    from the ContextVar when their own `cluster_id` parameter is None.
+    Explicit parameter still wins (precedence: explicit > ContextVar >
+    None). Safe for nested scopes via ContextVar reset.
+
+    cluster_id=None is also valid (no-op scope; preserves backward compat).
+    """
+    token = _CURRENT_CLUSTER_ID.set(cluster_id)
+    try:
+        yield
+    finally:
+        _CURRENT_CLUSTER_ID.reset(token)
+
+
+def _resolve_cluster_id(explicit: Optional[str]) -> Optional[str]:
+    """Resolve effective cluster_id: explicit param > ContextVar > None."""
+    if explicit is not None:
+        return explicit
+    return _CURRENT_CLUSTER_ID.get()
+
+
+def _wire_composition_for_entity(entity_id: str) -> None:
+    """feed an entity's full per-axiom verdict snapshot to the
+    axiom-composition wiring at the recording callsite (was callsite-less —
+    the established pattern substrate-callsite gap, review Part 66 / ARCHITECTURE Part 65.3).
+
+    Reads the wire-up gate dynamically so it stays byte-identical when
+    ``DT_AXIOM_COMPOSITION_WIRING_ENABLED`` is OFF (default): early-return, no
+    snapshot build, no state change. When ON, rebuilds the entity's per-axiom
+    snapshot from ``_PRODUCTION_LAST_VERDICT`` and registers it so
+    ``get_axiom_composition_wired_entity_count()`` becomes nonzero (which is
+    what flips ``/dt-axiom-verdicts`` from ``warming_up`` to ``ready``).
+    """
+    try:
+        from arbiter_engine.ontology import (
+            axiom_composition_wiring as _acw,
+        )
+    except Exception:  # noqa: BLE001 — composition wiring not deployed
+        return
+    if not _acw.DT_AXIOM_COMPOSITION_WIRING_ENABLED:
+        return
+    with _PRODUCTION_LOCK:
+        snapshot = {
+            ax: v
+            for (eid, ax), v in _PRODUCTION_LAST_VERDICT.items()
+            if eid == entity_id
+        }
+    if snapshot:
+        _acw.wire_axiom_composition_for_entity(entity_id, snapshot)
+
+
+def record_axiom_verdict(
+    axiom_name: str,
+    entity_id: str,
+    verdict: str,
+    confidence: float,
+    emit_policy: Optional[str] = None,
+    cluster_id: Optional[str] = None,
+) -> Optional[ProductionAxiomVerdict]:
+    """Record an axiom-verdict event at production-readiness shape.
+
+    Returns the stored ProductionAxiomVerdict when gate enabled AND
+    emit_policy admits the event; returns None when gate off OR
+    emit_policy suppressed OR hybrid mode rejects (verdict-transition OR confidence >= threshold) gate.
+
+    Hybrid mode gate: admits if (a) prior verdict for (entity_id,
+    axiom_name) differs from current, OR (b) confidence >= threshold.
+
+     (Bucket A): optional ``cluster_id`` stamps the record
+    so per-cluster retrieval queries can filter. Default None preserves
+    previously emission behavior (callsites that don't pass cluster_id
+    still record verdicts — they're then queryable via the global path
+    `get_axiom_verdicts()` but excluded from filtered queries).
+    """
+    if not DT_AXIOM_VERDICT_PRODUCTION_ENABLED:
+        return None
+    policy = resolve_production_axiom_verdict_emit_policy(emit_policy)
+    if policy == PRODUCTION_AXIOM_VERDICT_EMIT_POLICY_SUPPRESSED:
+        return None
+    key = (entity_id, axiom_name)
+    if policy == PRODUCTION_AXIOM_VERDICT_EMIT_POLICY_HYBRID:
+        with _PRODUCTION_LOCK:
+            prior_verdict = _PRODUCTION_LAST_VERDICT.get(key)
+        verdict_transition = (prior_verdict is None) or (prior_verdict != verdict)
+        confidence_crosses = float(confidence) >= DT_AXIOM_VERDICT_CONFIDENCE_THRESHOLD
+        if not (verdict_transition or confidence_crosses):
+            return None
+    # Layer 3: explicit cluster_id wins; fall back to ContextVar
+    # set by `cluster_scope(cluster_id)` in the caller (typically the full system
+    # detect-loop wrapper). None when neither is set (previously path).
+    effective_cluster_id = _resolve_cluster_id(cluster_id)
+    record = ProductionAxiomVerdict(
+        axiom_name=axiom_name,
+        entity_id=entity_id,
+        verdict=verdict,
+        confidence=float(confidence),
+        emit_policy_per_cd1098=policy,
+        cluster_id=effective_cluster_id,
+    )
+    with _PRODUCTION_LOCK:
+        _PRODUCTION_VERDICTS.append(record)
+        _PRODUCTION_LAST_VERDICT[key] = verdict
+        if len(_PRODUCTION_VERDICTS) > DT_AXIOM_VERDICT_PRODUCTION_RING_CAP:
+            del _PRODUCTION_VERDICTS[
+                : len(_PRODUCTION_VERDICTS) - DT_AXIOM_VERDICT_PRODUCTION_RING_CAP
+            ]
+    # land the previously-callsite-less axiom-composition wire so
+    # composition_wired_count can be nonzero. Self-gated on the established pattern
+    # DT_AXIOM_COMPOSITION_WIRING_ENABLED (default OFF -> no-op, byte-identical).
+    _wire_composition_for_entity(entity_id)
+    return record
+
+
+def _filter_by_cluster_id(
+    verdicts: List[ProductionAxiomVerdict],
+    cluster_id: Optional[str],
+) -> List[ProductionAxiomVerdict]:
+    """ helper: filter verdicts by cluster_id when non-None.
+
+    cluster_id=None returns the full list (backward compat).
+    cluster_id="X" returns only verdicts with v.cluster_id == "X".
+    Verdicts emitted previously have cluster_id=None and are
+    excluded from any non-None filter (signaling "not scoped").
+    Mirror of the RCA `_filter_by_cluster_id` pattern.
+    """
+    if cluster_id is None:
+        return verdicts
+    return [v for v in verdicts if v.cluster_id == cluster_id]
+
+
+def get_axiom_verdicts(
+    cluster_id: Optional[str] = None,
+) -> List[ProductionAxiomVerdict]:
+    """All recorded production axiom-verdict records. Empty when gate off.
+
+    optional ``cluster_id`` filter. None = all (backward compat);
+    string value returns only verdicts stamped with that cluster_id.
+    """
+    if not DT_AXIOM_VERDICT_PRODUCTION_ENABLED:
+        return []
+    with _PRODUCTION_LOCK:
+        all_verdicts = list(_PRODUCTION_VERDICTS)
+    return _filter_by_cluster_id(all_verdicts, cluster_id)
+
+
+def get_axiom_verdict_count(cluster_id: Optional[str] = None) -> int:
+    """Aggregate count of recorded production axiom-verdict records.
+
+    Dashboard-data defensive-accessor entry point + Pattern
+    171. Returns 0 when gate off.
+
+    optional ``cluster_id`` filter. None = aggregate count;
+    string value returns count of verdicts stamped with that cluster_id.
+    """
+    if not DT_AXIOM_VERDICT_PRODUCTION_ENABLED:
+        return 0
+    return len(get_axiom_verdicts(cluster_id=cluster_id))
+
+
+def get_latest_verdict_for_entity(
+    entity_id: str, axiom_name: str,
+) -> Optional[str]:
+    """Last-known verdict for (entity_id, axiom_name); None when unknown
+    or gate off."""
+    if not DT_AXIOM_VERDICT_PRODUCTION_ENABLED:
+        return None
+    with _PRODUCTION_LOCK:
+        return _PRODUCTION_LAST_VERDICT.get((entity_id, axiom_name))
+
+
+def known_verdict_axioms() -> List[str]:
+    """Diagnostic accessor — sorted unique axiom_name values."""
+    if not DT_AXIOM_VERDICT_PRODUCTION_ENABLED:
+        return []
+    with _PRODUCTION_LOCK:
+        return sorted({r.axiom_name for r in _PRODUCTION_VERDICTS})
+
+
+def _reset_production_verdicts_for_tests() -> None:
+    with _PRODUCTION_LOCK:
+        _PRODUCTION_VERDICTS.clear()
+        _PRODUCTION_LAST_VERDICT.clear()

arbiter_engine/ontology/axioms/__init__.py

@@ -0,0 +1,26 @@
+"""
+Per-axiom checker implementations.
+
+Each axiom has its own checker that implements the detection logic
+based on the mathematical definitions in the architecture document.
+"""
+
+from .stability import StabilityChecker
+from .boundedness import BoundednessChecker
+from .connectivity import ConnectivityChecker
+from .consistency import ConsistencyChecker
+from .responsiveness import ResponsivenessChecker
+from .homeostasis import HomeostasisChecker
+from .conservation import ConservationChecker
+from .monotonicity import MonotonicityChecker
+
+__all__ = [
+    'StabilityChecker',
+    'BoundednessChecker',
+    'ConnectivityChecker',
+    'ConsistencyChecker',
+    'ResponsivenessChecker',
+    'HomeostasisChecker',
+    'ConservationChecker',
+    'MonotonicityChecker',
+]