# Full Schema RPC Endpoint

## Overview

The `plexus_full_schema` endpoint returns complete method schemas including parameter types and return (stream event) types. This enables clients to understand both what to send and what to expect back.

## RPC Call

```json
{"jsonrpc":"2.0","id":1,"method":"plexus_full_schema","params":["<namespace>"]}
```

**Parameters:**
- `namespace` (string, required): The activation namespace (e.g., "bash", "arbor", "cone")

**Connection:** WebSocket to `ws://localhost:4444`

## Response Format

The response is a subscription that emits:
1. A `data` message with the full schema
2. A `done` message signaling completion

### Data Message Structure

```json
{
  "jsonrpc": "2.0",
  "method": "plexus_full_schema",
  "params": {
    "subscription": <id>,
    "result": {
      "plexus_hash": "<hash>",
      "type": "data",
      "provenance": {"segments": ["plexus"]},
      "content_type": "plexus.full_schema",
      "data": <ActivationFullSchema>
    }
  }
}
```

### ActivationFullSchema

```typescript
interface ActivationFullSchema {
  namespace: string;
  version: string;
  description: string;
  methods: MethodSchemaInfo[];
}

interface MethodSchemaInfo {
  name: string;
  description: string;
  params?: JSONSchema;    // Input parameters schema
  returns?: JSONSchema;   // Stream event schema (what the method yields)
}
```

## Example: Bash Activation

**Request:**
```json
{"jsonrpc":"2.0","id":1,"method":"plexus_full_schema","params":["bash"]}
```

**Response (data field):**
```json
{
  "namespace": "bash",
  "version": "1.0.0",
  "description": "Execute bash commands and stream output",
  "methods": [{
    "name": "execute",
    "description": "Execute a bash command and stream stdout, stderr, and exit code",
    "params": {
      "type": "object",
      "title": "ExecuteParams",
      "properties": {
        "command": {
          "description": "The command parameter",
          "type": "string"
        }
      },
      "required": ["command"]
    },
    "returns": {
      "title": "BashEvent",
      "description": "Stream events from bash command execution",
      "oneOf": [
        {
          "description": "Standard output line",
          "type": "object",
          "properties": {
            "type": {"const": "stdout", "type": "string"},
            "line": {"type": "string"}
          },
          "required": ["type", "line"]
        },
        {
          "description": "Standard error line",
          "type": "object",
          "properties": {
            "type": {"const": "stderr", "type": "string"},
            "line": {"type": "string"}
          },
          "required": ["type", "line"]
        },
        {
          "description": "Exit code when process completes",
          "type": "object",
          "properties": {
            "type": {"const": "exit", "type": "string"},
            "code": {"type": "integer", "format": "int32"}
          },
          "required": ["type", "code"]
        }
      ]
    }
  }]
}
```

## Comparison with plexus_activation_schema

| Aspect | `plexus_activation_schema` | `plexus_full_schema` |
|--------|---------------------------|---------------------|
| Params | Method enum with params | Structured params with field names |
| Returns | Not included | Full stream event schema |
| Use case | Method discovery | Client codegen, documentation |

## Client Usage

### Discovering Available Methods

```bash
# List all activations
(echo '{"jsonrpc":"2.0","id":1,"method":"plexus_schema","params":[]}'; sleep 1) | websocat ws://localhost:4444

# Get full schema for specific activation
(echo '{"jsonrpc":"2.0","id":1,"method":"plexus_full_schema","params":["bash"]}'; sleep 1) | websocat ws://localhost:4444
```

### Calling a Method

Once you have the schema, call the method using the params structure:

```json
{"jsonrpc":"2.0","id":1,"method":"bash_execute","params":{"command":"echo hello"}}
```

Or with positional params (first param value):
```json
{"jsonrpc":"2.0","id":1,"method":"bash_execute","params":["echo hello"]}
```

## Implementation Notes

- Schema is generated at compile time via the `#[hub_methods]` macro
- Return types are extracted from `impl Stream<Item = T>` signatures
- Params structs are auto-generated for proper JSON Schema output
- Default implementation returns basic info for non-macro activations
