alkcall/docs/architecture/decisions/030-peer-composite-env-peer-operations.md

# ADR-030: PeerCompositeEnv::peer_operations Override

## Status

Accepted (implemented 2026-09-04 — surfaced as UP-03 in alkhttp's
review 006 `docs/…/006-alkcall-0.3.0-consequence-review.md`: the
`op/register` amendment's "announced op is discoverable via
`services/list-peers`" promise did not resolve on the wire because
this override had never been ported into alkcall; the gate is
`announced_op_is_discoverable_via_services_list_peers` in
`src/registry/op_register.rs`. The `services/list-peers` unit tests
did not catch it because they mock `peer_operations` with hand-rolled
envs.)

## Context

`OperationEnv::peer_operations` (defined in `registry/env.rs:63-65`) has a
default implementation returning `Vec::new()`. `PeerCompositeEnv` overrides
`invoke_with_policy`, `contains`, `invoke_peer`, `peer_contains`, and
`peer_ids` — but does **not** override `peer_operations`. This means
`peer_operations` on a `PeerCompositeEnv` always returns an empty `Vec`.

The `services/list-peers` handler (`registry/discovery.rs:245-296`) calls
`ctx.env.peer_operations(&peer_id)` to discover what operations each peer
serves. Since `PeerCompositeEnv` does not override this, non-local peers
always show empty operation lists in the `list-peers` response. The
`peer_ids()` method correctly returns the peer IDs, but the operations for
each peer are always empty.

This is a pure gap — the `services/list-peers` handler is specced to enumerate
each peer's operations (ADR-024 §6), and the `PeerCompositeEnv` type has all
the data needed to implement it (each peer's `OverlayOperationEnv` holds a
`HashMap<String, HandlerRegistration>`). The override is one method collecting
each peer overlay's registered op names.

The alkapi project identified this as gap G.6: a hub consumer calling
`services/list-peers` gets `peers: [{peer_id: "dev1", operations: []}]` until
this is fixed.

## Decision

`PeerCompositeEnv` overrides `peer_operations` to collect the operation names
from each peer's connection overlay:

```rust
fn peer_operations(&self, peer: &PeerId) -> Vec<String> {
    match self.connections.get(peer) {
        Some(overlay) => {
            // The overlay is an OverlayOperationEnv wrapping a
            // HashMap<String, HandlerRegistration>. We need the op names.
            // Rather than adding a method to OperationEnv (which would
            // require every impl to add it), we use the existing `contains`
            // method — but that requires knowing the name to check.
            //
            // The correct approach: iterate the overlay's known names.
            // OverlayOperationEnv already has the data (the HashMap keys).
            // We add a `list_operation_names(&self) -> Vec<String>` method
            // to OperationEnv with a default returning Vec::new(), and
            // OverlayOperationEnv overrides it to return the keys.
            overlay.list_operation_names()
        }
        None => Vec::new(),
    }
}
```

### 1. `OperationEnv` gains `list_operation_names` with a default impl

```rust
fn list_operation_names(&self) -> Vec<String> {
    Vec::new()
}
```

The default returns empty — existing impls (`LocalOperationEnv`, test-only
envs) don't need to change. Only `OverlayOperationEnv` overrides it.

### 2. `OverlayOperationEnv` overrides `list_operation_names`

```rust
impl OperationEnv for OverlayOperationEnv {
    fn list_operation_names(&self) -> Vec<String> {
        self.overlay.read().keys().cloned().collect()
    }
    // ... existing impl unchanged
}
```

### 3. `PeerCompositeEnv::peer_operations` uses `list_operation_names`

The override delegates to each peer's overlay:

```rust
fn peer_operations(&self, peer: &PeerId) -> Vec<String> {
    self.connections
        .get(peer)
        .map(|overlay| overlay.list_operation_names())
        .unwrap_or_default()
}
```

### Why a new trait method instead of a different approach

Alternatives considered:

- **Add `fn operations(&self) -> Vec<String>` to `OperationEnv`**: Same
  concept, different name. `list_operation_names` is chosen to match the
  existing `list_operations` naming on `OperationRegistry`.
- **Make `peer_operations` on `PeerCompositeEnv` reach into
  `OverlayOperationEnv`'s internals**: Requires `OverlayOperationEnv` to
  expose its `HashMap` or a method. The trait method is cleaner — it keeps
  the abstraction boundary intact.
- **Have `services/list-peers` iterate `ctx.env.peer_ids()` and call
  `contains` for every known op name**: Requires knowing all possible op
  names (from the registry), which is a cross-layer coupling. The trait
  method keeps the data where it lives.

The trait method is the smallest surface change: one new method with a
default impl, one override on `OverlayOperationEnv`, one override on
`PeerCompositeEnv`. No existing code changes.

## Consequences

**Positive:**
- `services/list-peers` returns actual operation lists for each peer. A hub
  consumer calling `services/list-peers` gets `peers: [{peer_id: "dev1",
  operations: [{name: "docker/container/exec", ...}, ...]}]` — the specced
  behavior.
- The fix is small: one trait method, two overrides. No existing code paths
  change.
- The `list_operation_names` method is generally useful — any future code
  that needs to enumerate an env's operations can use it.

**Negative:**
- `OperationEnv` gains a method. The default impl preserves back-compat for
  all existing implementors. Only `OverlayOperationEnv` and
  `PeerCompositeEnv` override it.
- The `OverlayOperationEnv` override holds the `RwLock` read for the
  duration of the `keys().cloned().collect()`. This is a `Vec<String>`
  allocation — cheap for typical peer operation counts (tens, not thousands).

## Assumptions

1. **`OverlayOperationEnv`'s `RwLock<HashMap<String, HandlerRegistration>>`
   read is cheap.** The lock is held only for the `keys()` iteration and
   `collect()`. Typical peer operation counts are small (tens of ops).
2. **`list_operation_names` is the right name.** It matches the existing
   `list_operations` naming on `OperationRegistry` and avoids confusion with
   `peer_operations` (which takes a `PeerId` parameter).

## References

- ADR-024 §6: `services/list-peers` opt-in peer-attributed re-export listing
- ADR-029: Aggregated Peer-Environment Wiring (sibling hub-wiring decision)
- ADR-028: from_call Is a Manual Free Function (sibling hub-wiring decision)
- `crates/alknet-call/src/registry/env.rs:63-65` — default `peer_operations`
- `crates/alknet-call/src/registry/env.rs:155-301` — `PeerCompositeEnv`
- `crates/alknet-call/src/protocol/connection.rs:305-397` —
  `OverlayOperationEnv`
- `crates/alknet-call/src/registry/discovery.rs:245-296` —
  `services_list_peers_handler`
- alkapi gap G.6: `PeerCompositeEnv::peer_operations` unimplemented