---
id: IR-17
title: "substrate: migrate Orcha to #[plexus_macros::child] (drop hub flag + hand-written plugin_children)"
status: Complete
type: implementation
blocked_by: [IR-3, IR-4, IR-20, IR-21]
unlocks: []
severity: Medium
target_repo: plexus-substrate
---

## Problem

Orcha (`src/activations/orcha/activation.rs`) is the last substrate activation still using the legacy `hub = true` attribute-arg pattern. With IR-5's deprecation warnings now live, every `cargo build` in substrate emits:

```
warning: use of deprecated constant
  `activations::orcha::activation::_PLEXUS_MACROS_DEPRECATED_HUB_FLAG_Orcha`:
  plexus-macros: the 'hub' argument is deprecated; hub mode is inferred automatically
  from #[child]-tagged methods. This argument will be removed in plexus-macros 0.6.
```

Orcha also maintains a hand-written `pub fn plugin_children(&self) -> Vec<ChildSummary>` (lines ~82–90) that returns a single `ChildSummary` for its Pm sub-activation. Post-IR-4, this override is no longer needed — the same effect falls out of a single `#[plexus_macros::child]` method with CHILD-8's synthesis.

## Upstream context — already landed

- **CHILD-3** (plexus-macros `7c2e8ac`): `#[plexus_macros::child]` method attribute.
- **CHILD-8** (plexus-macros `eac7cb2f`): hub-mode inferred from presence of `#[child]` methods — no `hub = true` flag needed.
- **IR-3** (plexus-macros `b6285a8`): role-tagged `MethodSchema` emission.
- **IR-4** (plexus-core `d45a437`): `PluginSchema.children` derived from role-tagged methods; `validate_no_collisions` relaxed.
- **CHILD-7 / IR-8** (substrate Solar): reference migration pattern.

## Required behavior

Rewrite the `#[plexus_macros::activation]` block on Orcha:

```rust
/// ... existing doc comments ...
#[plexus_macros::activation(namespace = "orcha", version = "1.0.0")]
impl Orcha {
    // ... all existing #[method] methods stay ...

    /// Project management subsystem.
    #[plexus_macros::child]
    fn pm(&self) -> Pm {
        (*self.pm).clone()
    }
}
```

Remove:
- The `hub` / `hub = true` attribute arg on the activation macro (if present) — inspect current state before touching.
- The hand-written `pub fn plugin_children(&self) -> Vec<ChildSummary>` body (lines ~82–90).
- Any hand-written `impl ChildRouter for Orcha` block if one exists (grep before editing).
- `use crate::plexus::ChildSummary` if no longer referenced after removal.

Preserve everything else exactly — all `#[method]` function bodies, all other imports, all orchestration logic.

## Wire-behavior preservation

| Request | Before | After |
|---|---|---|
| `orcha.<method>` (any top-level RPC method) | Works | Identical |
| `orcha.pm.<method>` (nested routing through Pm) | Works | Identical |
| `orcha.plugin_schema()` | Returns `children: [pm]`, `is_hub: true` | Identical (derived from the `#[child] fn pm` method via IR-4's shim) |

## Regression requirements

- `cargo build -p plexus-substrate` passes with **no** `_PLEXUS_MACROS_DEPRECATED_HUB_FLAG_Orcha` warning.
- `cargo test -p plexus-substrate` passes — all existing Orcha-related tests pass without modification (unless the only change is the now-absent hand-written method, which Orcha's own tests shouldn't reference).
- Solar's wire behavior is unchanged (IR-4 golden snapshot still byte-identical).
- Orcha's `plugin_schema()` contains a `children` entry for `pm` with the same `namespace` and (roughly) `description` as the pre-ticket hand-written override produced. `hash` may go from populated to empty string (per CHILD-8 synthesis semantics) — document if so. Tests that assert on `hash` contents specifically need updating; tests that check presence/absence still pass.

## Acceptance criteria

1. `cargo build -p plexus-substrate` passes.
2. `grep -c "_PLEXUS_MACROS_DEPRECATED_HUB_FLAG_Orcha"` across substrate build output returns 0 (deprecation warning silenced).
3. `grep -c "pub fn plugin_children" src/activations/orcha/activation.rs` returns 0 (hand-written override removed).
4. `grep -c "hub[,)]" src/activations/orcha/activation.rs` matches ONLY in contexts unrelated to the activation attribute (e.g., comments, struct fields, or the Plexus RPC hub concept — verify no remaining `hub` attribute arg).
5. `cargo test -p plexus-substrate` passes.
6. Orcha's generated `plugin_schema()` (verified via a small test) contains a `methods` entry with `role: MethodRole::StaticChild` named `pm`.
7. Runtime nested routing `orcha.pm.<method>` still resolves end-to-end (verified via existing integration test if one exists, or a new small unit test).

## Risks

| Risk | Mitigation |
|---|---|
| Hash field on the derived `ChildSummary` for `pm` goes from populated to empty; a downstream consumer relies on it. | Unknown downstream reliance. Flag in PR. If a test breaks on hash value, either accept the change (transitional) or restore a tiny hand-written `fn pm_summary(&self) -> Vec<ChildSummary>` + `#[plexus_macros::child_summaries]` override (if CHILD-10-style override lands) — but don't ship that workaround in this ticket. |
| Orcha's `Pm` is wrapped in `Arc<Pm>` on the struct; `fn pm(&self) -> Pm` returns the inner `Pm`, which must be `Clone`. | `Pm` is `Clone` today (verify before starting). If it isn't, use `fn pm(&self) -> Arc<Pm>` — `ChildRouter` should accept either, as long as the return type implements `ChildRouter + Clone + Send + Sync`. |
| Existing tests that query `orcha.plugin_schema().children[0].hash` and assert non-empty. | Expected to require an update; IR-8's Solar migration handled the analogous case. |

## What must NOT change

- Any `#[method]` function body on Orcha.
- Orcha's `namespace`, `version`, or any other `#[plexus_macros::activation]` attribute arg besides the removed `hub`.
- Pm's surface (this ticket touches Orcha only).
- Solar's tests or source.
- Orcha's routing behavior at the wire level (nested `orcha.pm.<method>` must continue to resolve).

## Completion

PR against plexus-substrate. `cargo build` clean of the `hub` deprecation warning for Orcha. Tests pass. Status flipped from `Ready` to `Complete` in the same commit.
