orchestrata_ultimate.gateway.method_table

Reference › orchestrata_ultimate › gateway › method_table

method_table is the single declarative list of the gateway's JSON-RPC methods (ADR-0099 rules 2 and 3). It is a module-level tuple of method_spec rows, one per method, built through the helper _m, which joins the owner class and attribute into a handler path and sets mutates to the opposite of read_only. A row is therefore mutating unless it carries an explicit read-only opt-out, so a method that is not marked fails closed. Each row names the handler class under the handlers package and can set expose=False to keep a method RPC-only. rpc reads the table to route calls, and mcp_transport reads it to generate MCP tools, so the two surfaces share one source of truth. See gateway.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

API

Constants

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/gateway/method_table.py

"""The gateway's declarative method table (ADR-0099 rules 2 and 3).

``METHODS`` is the single source of the gateway's JSON-RPC surface. Both
transports read it: ``rpc._build_method_registry`` builds ``RPCHandler``'s
dispatch dict from it, and ``McpTransport`` builds the MCP tool list from it.
The module imports no handler -- each row names its handler by dotted path --
so it is importable without constructing a ConnectionManager, PubSub, ring
buffer or audit writer.

Marking rules (each confirmed by reading the handler, not by the name):

- ``mutates`` is ``True`` unless a row says ``read_only=True``; an unmarked
  method is approval-gated (fails closed).
- ``expose=False`` for streaming methods (the call returns a subscription;
  events then arrive as pushes an MCP request/response cannot carry), legacy
  aliases of a ``gateway.*`` method, and ``auth.authenticate`` (the MCP
  transport authenticates itself).

Author: Mohamed
"""

# Spec: 014 - WebSocket Gateway

from __future__ import annotations

from orchestrata_ultimate.gateway.method_spec import MethodSpec

_H = "orchestrata_ultimate.gateway.handlers"
_GATEWAY = f"{_H}.gateway.GatewayHandler"
_CXP = f"{_H}.cxp.CxpHandler"
_VOLK = f"{_H}.volk.VolkHandler"
_SESSION = f"{_H}.session.SessionHandler"
_GOVERNANCE = f"{_H}.governance.GovernanceHandler"
_KNOWLEDGE = f"{_H}.knowledge.KnowledgeHandler"
_PROJECTS = f"{_H}.projects.ProjectsHandler"
_ORCHESTRATOR = f"{_H}.orchestrator.OrchestratorHandler"
_TUI = f"{_H}.ultimatetui.UltimateTUIHandler"
_STATE = f"{_H}.state.StateHandler"
_AUTH = f"{_H}.auth.AuthHandler"
_FIREFLIES = f"{_H}.fireflies.FirefliesHandler"
_MEMORY = f"{_H}.memory.MemoryHandler"
_TEST_METRICS = f"{_H}.test_metrics.TestMetricsHandler"
_WORKFLOW = f"{_H}.workflow.WorkflowHandler"
_CONFIG = f"{_H}.config.ConfigHandler"


def _m(
    name: str,
    owner: str,
    attribute: str,
    description: str,
    *,
    read_only: bool = False,
    expose: bool = True,
) -> MethodSpec:
    """One table row; ``read_only`` is the explicit opt-out of the gate."""
    return MethodSpec(
        name=name,
        handler=f"{owner}.{attribute}",
        mutates=not read_only,
        expose=expose,
        description=description,
    )


METHODS: tuple[MethodSpec, ...] = (
    # Gateway (FR-020)
    _m("gateway.ping", _GATEWAY, "handle_ping", "Liveness ping.", read_only=True),
    _m(
        "gateway.info",
        _GATEWAY,
        "handle_info",
        "Gateway version, uptime, kernel status and capabilities.",
        read_only=True,
    ),
    _m(
        "gateway.clients",
        _GATEWAY,
        "handle_clients",
        "List the connected gateway clients.",
        read_only=True,
    ),
    _m(
        "gateway.replay",
        _GATEWAY,
        "handle_replay",
        "Replay recent events of a topic from the ring buffer (topic, count).",
        read_only=True,
    ),
    # Legacy short names (backward compat): aliases and streaming, RPC-only
    _m(
        "ping",
        _GATEWAY,
        "handle_ping",
        "Legacy alias of gateway.ping.",
        read_only=True,
        expose=False,
    ),
    _m(
        "subscribe",
        _GATEWAY,
        "handle_subscribe",
        "Subscribe to a topic (stream).",
        expose=False,
    ),
    _m(
        "unsubscribe",
        _GATEWAY,
        "handle_unsubscribe",
        "Drop a subscription.",
        expose=False,
    ),
    _m(
        "publish",
        _GATEWAY,
        "handle_publish",
        "Publish to a topic (stream).",
        expose=False,
    ),
    _m(
        "connections.list",
        _GATEWAY,
        "handle_clients",
        "Legacy alias of gateway.clients.",
        read_only=True,
        expose=False,
    ),
    _m(
        "connections.info",
        _GATEWAY,
        "handle_connections_info",
        "Legacy: one connection's info.",
        read_only=True,
        expose=False,
    ),
    # CXP (FR-015)
    _m("cxp.send", _CXP, "handle_send", "Send a CXP packet or chat message."),
    _m(
        "cxp.subscribe",
        _CXP,
        "handle_subscribe",
        "Subscribe to CXP traffic (stream).",
        expose=False,
    ),
    _m(
        "cxp.unsubscribe",
        _CXP,
        "handle_unsubscribe",
        "Drop a CXP subscription.",
        expose=False,
    ),
    _m(
        "cxp.status",
        _CXP,
        "handle_status",
        "Observed delivery status of a CXP thread (thread_id).",
        read_only=True,
    ),
    # Volk (FR-016)
    _m("volk.list", _VOLK, "handle_list", "List registered volks.", read_only=True),
    _m("volk.get", _VOLK, "handle_get", "Get one volk by name.", read_only=True),
    _m("volk.register", _VOLK, "handle_register", "Register a volk (admin token)."),
    _m(
        "volk.deregister",
        _VOLK,
        "handle_deregister",
        "Deregister a volk (admin token).",
    ),
    _m(
        "volk.lifecycle",
        _VOLK,
        "handle_lifecycle",
        "Subscribe to volk lifecycle events (stream).",
        expose=False,
    ),
    # Session (FR-017)
    _m("session.list", _SESSION, "handle_list", "List sessions.", read_only=True),
    _m(
        "session.get",
        _SESSION,
        "handle_get",
        "Get one session with context and facts (session_id).",
        read_only=True,
    ),
    _m(
        "session.active",
        _SESSION,
        "handle_active",
        "The most recent active session.",
        read_only=True,
    ),
    _m("session.open", _SESSION, "handle_open", "Open a session."),
    _m("session.close", _SESSION, "handle_close", "Close a session."),
    _m(
        "session.events",
        _SESSION,
        "handle_events",
        "Subscribe to session events (stream).",
        expose=False,
    ),
    _m(
        "session.facts.subscribe",
        _SESSION,
        "handle_facts_subscribe",
        "Subscribe to session facts (stream).",
        expose=False,
    ),
    # Governance (FR-018)
    _m(
        "governance.decisions",
        _GOVERNANCE,
        "handle_decisions",
        "Subscribe to governance decisions (stream).",
        expose=False,
    ),
    _m(
        "governance.query",
        _GOVERNANCE,
        "handle_query",
        "Historical governance decisions from the audit trail.",
        read_only=True,
    ),
    # evaluate publishes a decision event: a side effect, so it stays gated
    _m(
        "governance.evaluate",
        _GOVERNANCE,
        "handle_evaluate",
        "Evaluate an intent against the PolicyEngine (publishes a decision event).",
    ),
    _m(
        "governance.rules",
        _GOVERNANCE,
        "handle_rules",
        "The active constitutional rule set.",
        read_only=True,
    ),
    # Knowledge (FR-019)
    _m(
        "knowledge.query",
        _KNOWLEDGE,
        "handle_query",
        "Run read-only Cypher against the operational graph.",
        read_only=True,
    ),
    _m(
        "knowledge.nodes",
        _KNOWLEDGE,
        "handle_nodes",
        "List graph nodes by type.",
        read_only=True,
    ),
    _m(
        "knowledge.relationships",
        _KNOWLEDGE,
        "handle_relationships",
        "List graph relationships by type.",
        read_only=True,
    ),
    _m(
        "knowledge.volk_work_context",
        _KNOWLEDGE,
        "handle_volk_work_context",
        "A volk's components, decisions and artifacts.",
        read_only=True,
    ),
    _m(
        "knowledge.component_work_context",
        _KNOWLEDGE,
        "handle_component_work_context",
        "Everything a volk needs to resume work on a component.",
        read_only=True,
    ),
    _m(
        "knowledge.coverage_history",
        _KNOWLEDGE,
        "handle_coverage_history",
        "Coverage history for sparklines.",
        read_only=True,
    ),
    _m(
        "knowledge.rtm_progress",
        _KNOWLEDGE,
        "handle_rtm_progress",
        "Requirements-traceability verified/total progress.",
        read_only=True,
    ),
    # Projects & Tasks (from the graph)
    _m("projects.list", _PROJECTS, "handle_list", "List projects.", read_only=True),
    _m(
        "projects.get",
        _PROJECTS,
        "handle_get",
        "Get a project with its tasks and sessions.",
        read_only=True,
    ),
    _m(
        "projects.tasks",
        _PROJECTS,
        "handle_tasks",
        "List tasks, optionally for one project.",
        read_only=True,
    ),
    _m("projects.taskCreate", _PROJECTS, "handle_task_create", "Create a task."),
    _m("projects.taskUpdate", _PROJECTS, "handle_task_update", "Update a task."),
    # Orchestrator (intent processing: dispatches work and spends tokens)
    _m(
        "orchestrator.intent",
        _ORCHESTRATOR,
        "handle_intent",
        "Submit a natural-language intent to the orchestrator.",
    ),
    # UltimateTUI (SPEC-050) -- CheetahClaws bridge
    _m("tui.edit", _TUI, "handle_edit", "Edit a workspace file."),
    _m("tui.intent", _TUI, "handle_intent", "Submit an intent through the TUI bridge."),
    _m(
        "tui.agents",
        _TUI,
        "handle_agents",
        "Agent roster with provider and model assignments.",
        read_only=True,
    ),
    _m(
        "tui.models",
        _TUI,
        "handle_models",
        "Available LLM profiles and the active one.",
        read_only=True,
    ),
    _m("tui.model_switch", _TUI, "handle_model_switch", "Switch the LLM profile."),
    _m(
        "tui.read",
        _TUI,
        "handle_read",
        "Read a workspace file (contained to the gateway workspace).",
        read_only=True,
    ),
    # State sync (UI extension)
    _m(
        "state.getAll",
        _STATE,
        "handle_get_all",
        "All state entries of this connection.",
        read_only=True,
    ),
    _m("state.putAll", _STATE, "handle_put_all", "Set many state entries."),
    _m("state.put", _STATE, "handle_put", "Set one state entry (key, value)."),
    _m("state.delete", _STATE, "handle_delete", "Delete one state entry (key)."),
    # Auth: the MCP transport authenticates itself
    _m(
        "auth.authenticate",
        _AUTH,
        "handle_authenticate",
        "Authenticate the connection.",
        expose=False,
    ),
    # Fireflies MCP bridge (SPEC-018 US-006)
    _m(
        "fireflies.transcripts",
        _FIREFLIES,
        "handle_transcripts",
        "Recent Fireflies meeting transcripts.",
        read_only=True,
    ),
    _m(
        "fireflies.transcript",
        _FIREFLIES,
        "handle_transcript",
        "One Fireflies transcript (transcript_id).",
        read_only=True,
    ),
    _m(
        "fireflies.search",
        _FIREFLIES,
        "handle_search",
        "Search Fireflies transcripts (query).",
        read_only=True,
    ),
    _m(
        "fireflies.summary",
        _FIREFLIES,
        "handle_summary",
        "AI summary of a Fireflies transcript.",
        read_only=True,
    ),
    _m(
        "fireflies.health",
        _FIREFLIES,
        "handle_health",
        "Fireflies API connectivity check.",
        read_only=True,
    ),
    _m(
        "fireflies.sync",
        _FIREFLIES,
        "handle_sync",
        "Pull recent transcripts into the knowledge graph.",
    ),
    # Memory (SPEC-010)
    _m("memory.store", _MEMORY, "handle_store", "Store a memory entry."),
    _m(
        "memory.retrieve",
        _MEMORY,
        "handle_retrieve",
        "Fetch one memory entry by key.",
        read_only=True,
    ),
    _m(
        "memory.search",
        _MEMORY,
        "handle_search",
        "Semantic search across stored memories.",
        read_only=True,
    ),
    _m("memory.delete", _MEMORY, "handle_delete", "Delete a memory entry."),
    # Test metrics: tests.run executes pytest
    _m("tests.run", _TEST_METRICS, "handle_tests_run", "Run the test suite."),
    _m(
        "metrics.current",
        _TEST_METRICS,
        "handle_metrics_current",
        "Current test metrics.",
        read_only=True,
    ),
    # Workflow control (SPEC-014 US-014-005, REQ-014-076..080)
    _m("workflow.start", _WORKFLOW, "handle_start", "Start a workflow."),
    _m("workflow.pause", _WORKFLOW, "handle_pause", "Pause a workflow."),
    _m("workflow.resume", _WORKFLOW, "handle_resume", "Resume a workflow."),
    _m("workflow.cancel", _WORKFLOW, "handle_cancel", "Cancel a workflow."),
    # Runtime config service (SPEC-014 US-014-005, REQ-014-081..085)
    _m(
        "config.get",
        _CONFIG,
        "handle_get",
        "Read runtime settings, optionally path-scoped.",
        read_only=True,
    ),
    _m(
        "config.watch",
        _CONFIG,
        "handle_watch",
        "Subscribe to config.changed (stream).",
        expose=False,
    ),
    _m("config.set", _CONFIG, "handle_set", "Set a runtime setting."),
)