mubit-sdk 0.7.0

use serde::Serialize;

#[derive(Clone, Copy, Debug, Serialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum Domain {
    Auth,
    Core,
    Control,
}

#[derive(Clone, Copy, Debug, Serialize, PartialEq, Eq)]
#[serde(rename_all = "UPPERCASE")]
pub enum HttpMethod {
    Get,
    Post,
    Delete,
}

#[derive(Clone, Copy, Debug, Serialize)]
pub struct OperationSpec {
    pub key: &'static str,
    pub domain: Domain,
    pub method_name: &'static str,
    pub http_method: HttpMethod,
    pub http_path: &'static str,
    pub grpc_service: &'static str,
    pub grpc_method: &'static str,
    pub run_id_field: Option<&'static str>,
    pub summary: &'static str,
    pub server_streaming: bool,
}

pub static OPERATIONS: &[OperationSpec] = &[
    // auth
    OperationSpec {
        key: "auth.health",
        domain: Domain::Auth,
        method_name: "health",
        http_method: HttpMethod::Get,
        http_path: "/v2/core/health",
        grpc_service: "CoreService",
        grpc_method: "Health",
        run_id_field: None,
        summary: "Runtime health check",
        server_streaming: false,
    },
    OperationSpec {
        key: "auth.create_user",
        domain: Domain::Auth,
        method_name: "create_user",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/auth/users",
        grpc_service: "CoreService",
        grpc_method: "CreateUser",
        run_id_field: None,
        summary: "Create user and issue one-time API key",
        server_streaming: false,
    },
    OperationSpec {
        key: "auth.rotate_user_api_key",
        domain: Domain::Auth,
        method_name: "rotate_user_api_key",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/auth/users/:username/rotate_key",
        grpc_service: "CoreService",
        grpc_method: "RotateUserApiKey",
        run_id_field: None,
        summary: "Rotate user's API key and return one-time replacement",
        server_streaming: false,
    },
    OperationSpec {
        key: "auth.revoke_user_api_key",
        domain: Domain::Auth,
        method_name: "revoke_user_api_key",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/auth/users/:username/revoke_key",
        grpc_service: "CoreService",
        grpc_method: "RevokeUserApiKey",
        run_id_field: None,
        summary: "Revoke user's active API key",
        server_streaming: false,
    },
    OperationSpec {
        key: "auth.list_users",
        domain: Domain::Auth,
        method_name: "list_users",
        http_method: HttpMethod::Get,
        http_path: "/v2/core/auth/users",
        grpc_service: "CoreService",
        grpc_method: "ListUsers",
        run_id_field: None,
        summary: "List all users (admin only)",
        server_streaming: false,
    },
    OperationSpec {
        key: "auth.get_user",
        domain: Domain::Auth,
        method_name: "get_user",
        http_method: HttpMethod::Get,
        http_path: "/v2/core/auth/users/:username",
        grpc_service: "CoreService",
        grpc_method: "GetUser",
        run_id_field: None,
        summary: "Get user details (admin or self)",
        server_streaming: false,
    },
    OperationSpec {
        key: "auth.delete_user",
        domain: Domain::Auth,
        method_name: "delete_user",
        http_method: HttpMethod::Delete,
        http_path: "/v2/core/auth/users/:username",
        grpc_service: "CoreService",
        grpc_method: "DeleteUser",
        run_id_field: None,
        summary: "Delete user (admin only)",
        server_streaming: false,
    },
    // core
    OperationSpec {
        key: "core.insert",
        domain: Domain::Core,
        method_name: "insert",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/insert",
        grpc_service: "CoreService",
        grpc_method: "Insert",
        run_id_field: Some("run_id"),
        summary: "Insert one memory/document node",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.batch_insert",
        domain: Domain::Core,
        method_name: "batch_insert",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/batch_insert",
        grpc_service: "CoreService",
        grpc_method: "BatchInsert",
        run_id_field: None,
        summary: "Batch insert nodes",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.search",
        domain: Domain::Core,
        method_name: "search",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/search",
        grpc_service: "CoreService",
        grpc_method: "Search",
        run_id_field: Some("run_id"),
        summary: "Semantic search",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.delete_node",
        domain: Domain::Core,
        method_name: "delete_node",
        http_method: HttpMethod::Delete,
        http_path: "/v2/core/node/:id",
        grpc_service: "CoreService",
        grpc_method: "DeleteNode",
        run_id_field: None,
        summary: "Delete one node",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.delete_run",
        domain: Domain::Core,
        method_name: "delete_run",
        http_method: HttpMethod::Delete,
        http_path: "/v2/core/runs/:run_id",
        grpc_service: "CoreService",
        grpc_method: "DeleteRun",
        run_id_field: Some("run_id"),
        summary: "Delete all data by run_id",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.create_session",
        domain: Domain::Core,
        method_name: "create_session",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/session/create",
        grpc_service: "CoreService",
        grpc_method: "CreateSession",
        run_id_field: None,
        summary: "Create control session",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.snapshot_session",
        domain: Domain::Core,
        method_name: "snapshot_session",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/session/:id/snapshot",
        grpc_service: "CoreService",
        grpc_method: "SnapshotSession",
        run_id_field: None,
        summary: "Snapshot session",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.load_session",
        domain: Domain::Core,
        method_name: "load_session",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/session/load",
        grpc_service: "CoreService",
        grpc_method: "LoadSession",
        run_id_field: None,
        summary: "Load session",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.commit_session",
        domain: Domain::Core,
        method_name: "commit_session",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/session/:id/commit",
        grpc_service: "CoreService",
        grpc_method: "CommitSession",
        run_id_field: None,
        summary: "Commit session",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.drop_session",
        domain: Domain::Core,
        method_name: "drop_session",
        http_method: HttpMethod::Delete,
        http_path: "/v2/core/session/:id/drop",
        grpc_service: "CoreService",
        grpc_method: "DropSession",
        run_id_field: None,
        summary: "Drop session",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.write_memory",
        domain: Domain::Core,
        method_name: "write_memory",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/sdm/write",
        grpc_service: "CoreService",
        grpc_method: "WriteMemory",
        run_id_field: None,
        summary: "SDM write",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.read_memory",
        domain: Domain::Core,
        method_name: "read_memory",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/sdm/read",
        grpc_service: "CoreService",
        grpc_method: "ReadMemory",
        run_id_field: None,
        summary: "SDM read",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.add_memory",
        domain: Domain::Core,
        method_name: "add_memory",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/memory/:session_id",
        grpc_service: "CoreService",
        grpc_method: "AddMemory",
        run_id_field: None,
        summary: "Add scratchpad memory",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.get_memory",
        domain: Domain::Core,
        method_name: "get_memory",
        http_method: HttpMethod::Get,
        http_path: "/v2/core/memory/:session_id",
        grpc_service: "CoreService",
        grpc_method: "GetMemory",
        run_id_field: None,
        summary: "Read scratchpad memory",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.clear_memory",
        domain: Domain::Core,
        method_name: "clear_memory",
        http_method: HttpMethod::Delete,
        http_path: "/v2/core/memory/:session_id",
        grpc_service: "CoreService",
        grpc_method: "ClearMemory",
        run_id_field: None,
        summary: "Clear scratchpad memory",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.grant_permission",
        domain: Domain::Core,
        method_name: "grant_permission",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/acl/grant",
        grpc_service: "CoreService",
        grpc_method: "GrantPermission",
        run_id_field: None,
        summary: "Grant ACL permission",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.revoke_permission",
        domain: Domain::Core,
        method_name: "revoke_permission",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/acl/revoke",
        grpc_service: "CoreService",
        grpc_method: "RevokePermission",
        run_id_field: None,
        summary: "Revoke ACL permission",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.check_permission",
        domain: Domain::Core,
        method_name: "check_permission",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/acl/check",
        grpc_service: "CoreService",
        grpc_method: "",
        run_id_field: None,
        summary: "Check ACL permission",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.subscribe_events",
        domain: Domain::Core,
        method_name: "subscribe_events",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/pubsub/subscribe",
        grpc_service: "CoreService",
        grpc_method: "Subscribe",
        run_id_field: None,
        summary: "Subscribe to pubsub events",
        server_streaming: true,
    },
    OperationSpec {
        key: "core.unsubscribe_events",
        domain: Domain::Core,
        method_name: "unsubscribe_events",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/pubsub/unsubscribe",
        grpc_service: "CoreService",
        grpc_method: "",
        run_id_field: None,
        summary: "Unsubscribe from pubsub events",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.list_subscriptions",
        domain: Domain::Core,
        method_name: "list_subscriptions",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/pubsub/list",
        grpc_service: "CoreService",
        grpc_method: "",
        run_id_field: None,
        summary: "List pubsub subscriptions",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.watch_memory",
        domain: Domain::Core,
        method_name: "watch_memory",
        http_method: HttpMethod::Get,
        http_path: "/v2/core/memory/watch",
        grpc_service: "CoreService",
        grpc_method: "WatchMemory",
        run_id_field: None,
        summary: "Watch memory events for a session",
        server_streaming: true,
    },
    OperationSpec {
        key: "core.storage_stats",
        domain: Domain::Core,
        method_name: "storage_stats",
        http_method: HttpMethod::Get,
        http_path: "/v2/core/storage/stats",
        grpc_service: "CoreService",
        grpc_method: "",
        run_id_field: None,
        summary: "Storage statistics",
        server_streaming: false,
    },
    OperationSpec {
        key: "core.trigger_compaction",
        domain: Domain::Core,
        method_name: "trigger_compaction",
        http_method: HttpMethod::Post,
        http_path: "/v2/core/storage/compact",
        grpc_service: "CoreService",
        grpc_method: "",
        run_id_field: None,
        summary: "Trigger storage compaction",
        server_streaming: false,
    },
    // control
    // Phase 2.7 (removed from SDK surface): Goals/Concepts/Variables/Actions/
    // Cycles CRUD were never exercised in public examples. Server stubs remain
    // for backward compatibility but the SDK no longer surfaces them. If a
    // customer later needs them, revive selectively with real examples.
    OperationSpec {
        key: "control.register_agent",
        domain: Domain::Control,
        method_name: "register_agent",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/agents/register",
        grpc_service: "ControlService",
        grpc_method: "RegisterAgent",
        run_id_field: Some("run_id"),
        summary: "Register agent",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.agent_heartbeat",
        domain: Domain::Control,
        method_name: "agent_heartbeat",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/agents/heartbeat",
        grpc_service: "ControlService",
        grpc_method: "AgentHeartbeat",
        run_id_field: Some("run_id"),
        summary: "Send agent heartbeat",
        server_streaming: false,
    },
    // Phase 2.7 (removed): control.append_activity dropped from SDK surface.
    OperationSpec {
        key: "control.context_snapshot",
        domain: Domain::Control,
        method_name: "context_snapshot",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/context/snapshot",
        grpc_service: "ControlService",
        grpc_method: "GetRunSnapshot",
        run_id_field: Some("run_id"),
        summary: "Fetch run context snapshot",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.link_run",
        domain: Domain::Control,
        method_name: "link_run",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/runs/link",
        grpc_service: "ControlService",
        grpc_method: "LinkRun",
        run_id_field: Some("run_id"),
        summary: "Link run",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.unlink_run",
        domain: Domain::Control,
        method_name: "unlink_run",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/runs/unlink",
        grpc_service: "ControlService",
        grpc_method: "UnlinkRun",
        run_id_field: Some("run_id"),
        summary: "Unlink run",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.ingest",
        domain: Domain::Control,
        method_name: "ingest",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/ingest",
        grpc_service: "ControlService",
        grpc_method: "Ingest",
        run_id_field: Some("run_id"),
        summary: "Submit async ingestion job to control ingestion agent",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.batch_insert",
        domain: Domain::Control,
        method_name: "batch_insert",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/batch_insert",
        grpc_service: "ControlService",
        grpc_method: "BatchInsert",
        run_id_field: Some("run_id"),
        summary: "Synchronously batch insert semantic memory into knowledge lane",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.get_ingest_job",
        domain: Domain::Control,
        method_name: "get_ingest_job",
        http_method: HttpMethod::Get,
        http_path: "/v2/control/ingest/jobs/:job_id",
        grpc_service: "ControlService",
        grpc_method: "GetIngestJob",
        run_id_field: Some("run_id"),
        summary: "Fetch ingestion job status and decision traces",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.get_run_ingest_stats",
        domain: Domain::Control,
        method_name: "get_run_ingest_stats",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/ingest/stats",
        grpc_service: "ControlService",
        grpc_method: "GetRunIngestStats",
        run_id_field: Some("run_id"),
        summary: "Fetch aggregate ingestion job stats for a run",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.query",
        domain: Domain::Control,
        method_name: "query",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/query",
        grpc_service: "ControlService",
        grpc_method: "Query",
        run_id_field: Some("run_id"),
        summary: "Execute control-plane query pipeline with optional direct bypass",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.diagnose",
        domain: Domain::Control,
        method_name: "diagnose",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/diagnose",
        grpc_service: "ControlService",
        grpc_method: "Diagnose",
        run_id_field: Some("run_id"),
        summary: "Surface failure lessons relevant to an error context",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.delete_run",
        domain: Domain::Control,
        method_name: "delete_run",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/delete_run",
        grpc_service: "ControlService",
        grpc_method: "DeleteRun",
        run_id_field: Some("run_id"),
        summary: "Delete control run",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.subscribe",
        domain: Domain::Control,
        method_name: "subscribe",
        http_method: HttpMethod::Get,
        http_path: "/v2/control/events/subscribe",
        grpc_service: "ControlService",
        grpc_method: "Subscribe",
        run_id_field: Some("run_id"),
        summary: "Subscribe to control events",
        server_streaming: true,
    },
    OperationSpec {
        key: "control.reflect",
        domain: Domain::Control,
        method_name: "reflect",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/reflect",
        grpc_service: "ControlService",
        grpc_method: "Reflect",
        run_id_field: Some("run_id"),
        summary: "Extract lessons from run evidence via reflection pipeline",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.lessons",
        domain: Domain::Control,
        method_name: "lessons",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/lessons",
        grpc_service: "ControlService",
        grpc_method: "ListLessons",
        run_id_field: Some("run_id"),
        summary: "List lessons from long-term memory",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.delete_lesson",
        domain: Domain::Control,
        method_name: "delete_lesson",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/lessons/delete",
        grpc_service: "ControlService",
        grpc_method: "DeleteLesson",
        run_id_field: None,
        summary: "Delete lesson from long-term memory",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.context",
        domain: Domain::Control,
        method_name: "context",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/context",
        grpc_service: "ControlService",
        grpc_method: "GetContext",
        run_id_field: Some("run_id"),
        summary: "Get pre-assembled memory context block for LLM prompt injection",
        server_streaming: false,
    },
    // Phase 2.7 (removed): control.list_activity / export_activity dropped
    // from SDK surface. Server stubs remain for backward compat.
    OperationSpec {
        key: "control.archive_block",
        domain: Domain::Control,
        method_name: "archive_block",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/archive",
        grpc_service: "ControlService",
        grpc_method: "ArchiveBlock",
        run_id_field: Some("run_id"),
        summary: "Store an exact reusable archive artifact and return a stable reference ID",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.dereference",
        domain: Domain::Control,
        method_name: "dereference",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/dereference",
        grpc_service: "ControlService",
        grpc_method: "Dereference",
        run_id_field: Some("run_id"),
        summary: "Fetch exact archived content by stable reference ID",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.memory_health",
        domain: Domain::Control,
        method_name: "memory_health",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/memory_health",
        grpc_service: "ControlService",
        grpc_method: "GetMemoryHealth",
        run_id_field: Some("run_id"),
        summary: "Inspect memory quality, staleness, and contradiction signals",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.checkpoint",
        domain: Domain::Control,
        method_name: "checkpoint",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/checkpoint",
        grpc_service: "ControlService",
        grpc_method: "Checkpoint",
        run_id_field: Some("run_id"),
        summary: "Store a durable pre-compaction checkpoint for the current run",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.list_agents",
        domain: Domain::Control,
        method_name: "list_agents",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/agents",
        grpc_service: "ControlService",
        grpc_method: "ListAgents",
        run_id_field: Some("run_id"),
        summary: "List registered agents for a run",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.create_handoff",
        domain: Domain::Control,
        method_name: "create_handoff",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/handoff",
        grpc_service: "ControlService",
        grpc_method: "CreateHandoff",
        run_id_field: Some("run_id"),
        summary: "Create agent-to-agent task handoff",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.submit_feedback",
        domain: Domain::Control,
        method_name: "submit_feedback",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/feedback",
        grpc_service: "ControlService",
        grpc_method: "SubmitFeedback",
        run_id_field: Some("run_id"),
        summary: "Submit feedback verdict for an existing handoff",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.record_outcome",
        domain: Domain::Control,
        method_name: "record_outcome",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/outcome",
        grpc_service: "ControlService",
        grpc_method: "RecordOutcome",
        run_id_field: Some("run_id"),
        summary: "Record reinforcement outcome feedback for a lesson or action",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.circuit_break",
        domain: Domain::Control,
        method_name: "circuit_break",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/circuit_break",
        grpc_service: "ControlService",
        grpc_method: "CircuitBreak",
        run_id_field: Some("run_id"),
        summary: "Atomic anti-loop reset: snapshot working memory, clear state, emit CIRCUIT_BROKEN",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.get_run_signal",
        domain: Domain::Control,
        method_name: "get_run_signal",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/run-monitor/signal",
        grpc_service: "ControlService",
        grpc_method: "GetRunSignal",
        run_id_field: Some("run_id"),
        summary: "Return the latest Phase B Run Monitor signal for a run (re-inspects on demand)",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.record_step_outcome",
        domain: Domain::Control,
        method_name: "record_step_outcome",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/step_outcome",
        grpc_service: "ControlService",
        grpc_method: "RecordStepOutcome",
        run_id_field: Some("run_id"),
        summary: "Record step-level process reward outcome during a run",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.surface_strategies",
        domain: Domain::Control,
        method_name: "surface_strategies",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/strategies",
        grpc_service: "ControlService",
        grpc_method: "SurfaceStrategies",
        run_id_field: Some("run_id"),
        summary: "Surface emergent strategies from reinforced lessons",
        server_streaming: false,
    },
    // Session lifecycle
    OperationSpec {
        key: "control.create_session",
        domain: Domain::Control,
        method_name: "create_session",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/sessions/create",
        grpc_service: "ControlService",
        grpc_method: "CreateControlSession",
        run_id_field: Some("run_id"),
        summary: "Create a server-managed control session with auto-generated IDs",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.get_session",
        domain: Domain::Control,
        method_name: "get_session",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/sessions/get",
        grpc_service: "ControlService",
        grpc_method: "GetControlSession",
        run_id_field: None,
        summary: "Get details of a control session by session ID",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.close_session",
        domain: Domain::Control,
        method_name: "close_session",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/sessions/close",
        grpc_service: "ControlService",
        grpc_method: "CloseControlSession",
        run_id_field: None,
        summary: "Close a control session, optionally triggering final reflection",
        server_streaming: false,
    },
    // Prompt lifecycle management
    OperationSpec {
        key: "control.set_prompt",
        domain: Domain::Control,
        method_name: "set_prompt",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/prompt/set",
        grpc_service: "ControlService",
        grpc_method: "SetPrompt",
        run_id_field: Some("run_id"),
        summary: "Set or update the system prompt for an agent (creates new version)",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.get_prompt",
        domain: Domain::Control,
        method_name: "get_prompt",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/prompt/get",
        grpc_service: "ControlService",
        grpc_method: "GetPrompt",
        run_id_field: None,
        summary: "Get the active (or specific version) system prompt for an agent",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.list_prompt_versions",
        domain: Domain::Control,
        method_name: "list_prompt_versions",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/prompt/versions",
        grpc_service: "ControlService",
        grpc_method: "ListPromptVersions",
        run_id_field: None,
        summary: "List prompt versions for an agent",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.activate_prompt_version",
        domain: Domain::Control,
        method_name: "activate_prompt_version",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/prompt/activate",
        grpc_service: "ControlService",
        grpc_method: "ActivatePromptVersion",
        run_id_field: None,
        summary: "Activate a specific prompt version for an agent",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.optimize_prompt",
        domain: Domain::Control,
        method_name: "optimize_prompt",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/prompt/optimize",
        grpc_service: "ControlService",
        grpc_method: "OptimizePrompt",
        run_id_field: Some("run_id"),
        summary: "Optimize an agent's system prompt using accumulated lessons and outcomes",
        server_streaming: false,
    },
    OperationSpec {
        key: "control.get_prompt_diff",
        domain: Domain::Control,
        method_name: "get_prompt_diff",
        http_method: HttpMethod::Post,
        http_path: "/v2/control/prompt/diff",
        grpc_service: "ControlService",
        grpc_method: "GetPromptDiff",
        run_id_field: None,
        summary: "Get a diff between two prompt versions",
        server_streaming: false,
    },
    // ── Project Management ──────────────────────────────────────
    OperationSpec { key: "control.create_project", domain: Domain::Control, method_name: "create_project", http_method: HttpMethod::Post, http_path: "/v2/control/projects", grpc_service: "ControlService", grpc_method: "CreateProject", run_id_field: None, summary: "Create a project", server_streaming: false },
    OperationSpec { key: "control.get_project", domain: Domain::Control, method_name: "get_project", http_method: HttpMethod::Post, http_path: "/v2/control/projects/get", grpc_service: "ControlService", grpc_method: "GetProject", run_id_field: None, summary: "Get project details", server_streaming: false },
    OperationSpec { key: "control.list_projects", domain: Domain::Control, method_name: "list_projects", http_method: HttpMethod::Post, http_path: "/v2/control/projects/list", grpc_service: "ControlService", grpc_method: "ListProjects", run_id_field: None, summary: "List all projects", server_streaming: false },
    OperationSpec { key: "control.update_project", domain: Domain::Control, method_name: "update_project", http_method: HttpMethod::Post, http_path: "/v2/control/projects/update", grpc_service: "ControlService", grpc_method: "UpdateProject", run_id_field: None, summary: "Update a project", server_streaming: false },
    OperationSpec { key: "control.delete_project", domain: Domain::Control, method_name: "delete_project", http_method: HttpMethod::Post, http_path: "/v2/control/projects/delete", grpc_service: "ControlService", grpc_method: "DeleteProject", run_id_field: None, summary: "Delete a project", server_streaming: false },
    // ── Agent Definitions ───────────────────────────────────────
    OperationSpec { key: "control.create_agent_definition", domain: Domain::Control, method_name: "create_agent_definition", http_method: HttpMethod::Post, http_path: "/v2/control/projects/agents", grpc_service: "ControlService", grpc_method: "CreateAgentDefinition", run_id_field: None, summary: "Create an agent definition", server_streaming: false },
    OperationSpec { key: "control.get_agent_definition", domain: Domain::Control, method_name: "get_agent_definition", http_method: HttpMethod::Post, http_path: "/v2/control/projects/agents/get", grpc_service: "ControlService", grpc_method: "GetAgentDefinition", run_id_field: None, summary: "Get agent definition", server_streaming: false },
    OperationSpec { key: "control.list_agent_definitions", domain: Domain::Control, method_name: "list_agent_definitions", http_method: HttpMethod::Post, http_path: "/v2/control/projects/agents/list", grpc_service: "ControlService", grpc_method: "ListAgentDefinitions", run_id_field: None, summary: "List agent definitions for a project", server_streaming: false },
    OperationSpec { key: "control.update_agent_definition", domain: Domain::Control, method_name: "update_agent_definition", http_method: HttpMethod::Post, http_path: "/v2/control/projects/agents/update", grpc_service: "ControlService", grpc_method: "UpdateAgentDefinition", run_id_field: None, summary: "Update an agent definition", server_streaming: false },
    OperationSpec { key: "control.delete_agent_definition", domain: Domain::Control, method_name: "delete_agent_definition", http_method: HttpMethod::Post, http_path: "/v2/control/projects/agents/delete", grpc_service: "ControlService", grpc_method: "DeleteAgentDefinition", run_id_field: None, summary: "Delete an agent definition", server_streaming: false },
    // ── Run History ─────────────────────────────────────────────
    OperationSpec { key: "control.list_run_history", domain: Domain::Control, method_name: "list_run_history", http_method: HttpMethod::Post, http_path: "/v2/control/projects/runs", grpc_service: "ControlService", grpc_method: "ListRunHistory", run_id_field: None, summary: "List run history for a project", server_streaming: false },
    OperationSpec { key: "control.get_run_history", domain: Domain::Control, method_name: "get_run_history", http_method: HttpMethod::Post, http_path: "/v2/control/projects/runs/get", grpc_service: "ControlService", grpc_method: "GetRunHistory", run_id_field: None, summary: "Get run history details", server_streaming: false },
    // ── Skills ──────────────────────────────────────────────────
    OperationSpec { key: "control.create_skill", domain: Domain::Control, method_name: "create_skill", http_method: HttpMethod::Post, http_path: "/v2/control/skills", grpc_service: "ControlService", grpc_method: "CreateSkill", run_id_field: None, summary: "Create a skill", server_streaming: false },
    OperationSpec { key: "control.get_skill", domain: Domain::Control, method_name: "get_skill", http_method: HttpMethod::Post, http_path: "/v2/control/skills/get", grpc_service: "ControlService", grpc_method: "GetSkill", run_id_field: None, summary: "Get skill details", server_streaming: false },
    OperationSpec { key: "control.list_skills", domain: Domain::Control, method_name: "list_skills", http_method: HttpMethod::Post, http_path: "/v2/control/skills/list", grpc_service: "ControlService", grpc_method: "ListSkills", run_id_field: None, summary: "List skills", server_streaming: false },
    OperationSpec { key: "control.update_skill", domain: Domain::Control, method_name: "update_skill", http_method: HttpMethod::Post, http_path: "/v2/control/skills/update", grpc_service: "ControlService", grpc_method: "UpdateSkill", run_id_field: None, summary: "Update a skill", server_streaming: false },
    OperationSpec { key: "control.delete_skill", domain: Domain::Control, method_name: "delete_skill", http_method: HttpMethod::Post, http_path: "/v2/control/skills/delete", grpc_service: "ControlService", grpc_method: "DeleteSkill", run_id_field: None, summary: "Delete a skill", server_streaming: false },
    OperationSpec { key: "control.list_skill_versions", domain: Domain::Control, method_name: "list_skill_versions", http_method: HttpMethod::Post, http_path: "/v2/control/skills/versions", grpc_service: "ControlService", grpc_method: "ListSkillVersions", run_id_field: None, summary: "List skill versions", server_streaming: false },
    OperationSpec { key: "control.activate_skill_version", domain: Domain::Control, method_name: "activate_skill_version", http_method: HttpMethod::Post, http_path: "/v2/control/skills/activate", grpc_service: "ControlService", grpc_method: "ActivateSkillVersion", run_id_field: None, summary: "Activate a skill version", server_streaming: false },
    OperationSpec { key: "control.optimize_skill", domain: Domain::Control, method_name: "optimize_skill", http_method: HttpMethod::Post, http_path: "/v2/control/skills/optimize", grpc_service: "ControlService", grpc_method: "OptimizeSkill", run_id_field: None, summary: "Optimize a skill", server_streaming: false },
    OperationSpec { key: "control.get_skill_diff", domain: Domain::Control, method_name: "get_skill_diff", http_method: HttpMethod::Post, http_path: "/v2/control/skills/diff", grpc_service: "ControlService", grpc_method: "GetSkillDiff", run_id_field: None, summary: "Get skill diff", server_streaming: false },
];

pub fn operations() -> &'static [OperationSpec] {
    OPERATIONS
}

pub fn find_operation(key: &str) -> Option<&'static OperationSpec> {
    OPERATIONS.iter().find(|op| op.key == key)
}

/// Phase 2.2: the canonical user-facing surface. These ~17 methods are the
/// "agents get better over time" entry points — everything else is
/// supporting / advanced surface that code-generators expose under
/// `client.advanced.*` (Python/JS) while keeping the top-level `client`
/// uncluttered.
pub const HIGH_LEVEL_METHODS: &[&str] = &[
    "health",
    "remember",
    "recall",
    "get_context",
    "forget",
    "reflect",
    "diagnose",
    "memory_health",
    "checkpoint",
    "archive",
    "dereference",
    "record_outcome",
    "record_step_outcome",
    "surface_strategies",
    "feedback",
    "handoff",
    "register_agent",
    "list_agents",
    "circuit_break",
    "get_run_signal",
    "optimize_prompt",
    "optimize_skill",
    // Common lesson-surface helpers — kept on top-level Client so the
    // canonical recall/remember/lessons flow doesn't trigger deprecation
    // noise in existing examples. They operate on lesson entries directly
    // and are indisputably part of the "agents get better over time" API.
    "lessons",
    "delete_lesson",
    "delete_run",
];

/// True when the given method name is on the canonical high-level surface.
/// Generators use this to decide whether to flat-bind or nest under
/// `advanced`.
pub fn is_high_level(method_name: &str) -> bool {
    HIGH_LEVEL_METHODS.iter().any(|m| *m == method_name)
}