# Shallow Schema API

## Overview

The `plexus.schema` RPC method now returns a **shallow schema** - the plugin's own schema with child namespaces listed as strings, not full recursive schemas.

## Before (Recursive)

```json
{
  "namespace": "plexus",
  "methods": [...],
  "children": [
    {
      "namespace": "solar",
      "methods": [...],
      "children": [
        {
          "namespace": "mercury",
          "methods": [...]
        },
        {
          "namespace": "earth",
          "methods": [...],
          "children": [
            {"namespace": "luna", "methods": [...]}
          ]
        }
        // ... entire tree
      ]
    }
    // ... all plugins fully expanded
  ]
}
```

## After (Shallow)

```json
{
  "namespace": "plexus",
  "version": "1.0.0",
  "description": "Central routing and introspection",
  "hash": "abc123...",
  "methods": [
    {
      "name": "call",
      "description": "Route a call to a registered activation",
      "hash": "...",
      "params": {"properties": {"method": {...}, "params": {...}}, "required": ["method"]}
    },
    {"name": "hash", ...},
    {"name": "schema", ...}
  ],
  "children": [
    {"namespace": "health", "description": "Check hub health and uptime", "hash": "c5bb0bb..."},
    {"namespace": "solar", "description": "Solar system model", "hash": "d2c8260..."},
    {"namespace": "echo", "description": "Echo messages back", "hash": "eb051e8..."}
  ]
}
```

## Key Changes

| Field | Type | Description |
|-------|------|-------------|
| `namespace` | `string` | Plugin namespace (e.g., "plexus") |
| `version` | `string` | Semantic version |
| `description` | `string` | Human-readable description |
| `hash` | `string` | Content hash for cache invalidation |
| `methods` | `MethodSchema[]` | Full method schemas with params/returns |
| `children` | `ChildSummary[] \| null` | Child summaries (namespace, description, hash) |

## Fetching Child Schemas

To get a child's schema, use `plexus.call`:

```json
{"method": "plexus.call", "params": {"method": "solar.schema"}}
```

**Note:** This requires the child activation to expose a `schema` method. Currently only `plexus` exposes one. To support this pattern, child activations would need their own schema methods.

## Optional Params

The `params` field in `plexus.call` is now **optional**:

```json
// Both work:
{"method": "plexus.call", "params": {"method": "health.check"}}
{"method": "plexus.call", "params": {"method": "health.check", "params": {}}}
```

Schema shows `"required": ["method"]` - only method is required.

## TypeScript Types

```typescript
interface ShallowPluginSchema {
  namespace: string;
  version: string;
  description: string;
  hash: string;
  methods: MethodSchema[];
  children?: ChildSummary[];
}

interface ChildSummary {
  namespace: string;
  description: string;
  hash: string;
}

interface MethodSchema {
  name: string;
  description: string;
  hash: string;
  params?: JSONSchema;   // JSON Schema for params
  returns?: JSONSchema;  // JSON Schema for return type
}
```

## RPC Examples

### Get plexus schema
```bash
wscat -c ws://localhost:4444
> {"jsonrpc":"2.0","id":1,"method":"plexus_schema","params":{}}
```

### Call a method (params optional)
```bash
> {"jsonrpc":"2.0","id":1,"method":"plexus_call","params":{"method":"health.check"}}
```

## Migration Notes

- **Breaking:** `plexus.schema` response shape changed - `children` is now `ChildSummary[]` not `PluginSchema[]`
- Each child summary includes `namespace`, `description`, and `hash` (for cache invalidation)
- **Non-breaking:** `plexus.call` params now optional
- Clients needing full recursive schema must fetch each child individually
