# TeamsISO Phase B-1 — Pipeline Orchestration Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Implement the engine-side pipeline orchestration on top of the `INdiInterop` test seam from Phase A — `NdiReceiver`, `NdiSender`, `ExponentialBackoff`, `NdiRuntimeProbe`, `IsoPipeline` (lifecycle + restart loop), and `IsoController` (top-level engine API). All testable on Linux against `FakeNdiInterop`. Phase B-2 (real Windows P/Invoke for `INdiInterop` + libyuv `IFrameScaler` + integration tests) follows.

**Architecture:** Pure orchestration. Each `IsoPipeline` wires one `NdiReceiver` → existing `FrameProcessor` → one `NdiSender` via two bounded channels. The pipeline owns a restart loop driven by `ExponentialBackoff`. `IsoController` is the top of the engine — holds the pipeline dictionary, the `ParticipantTracker`, the `ConfigStore`, and exposes the contract the WPF host (Phase C) will bind to.

**Tech Stack:** .NET 8, xUnit, FluentAssertions. No new external dependencies.

**Source spec:** `docs/superpowers/specs/2026-05-07-teamsiso-v1-design.md`

---

## File structure additions

```
src/TeamsISO.Engine/
├── Pipeline/
│   ├── NdiReceiver.cs              (NEW)
│   ├── NdiSender.cs                (NEW)
│   ├── ExponentialBackoff.cs       (NEW)
│   ├── IsoPipeline.cs              (NEW)
│   └── IsoPipelineConfig.cs        (NEW)
├── Interop/
│   └── NdiRuntimeProbe.cs          (NEW)
└── Controller/
    ├── IIsoController.cs           (NEW)
    └── IsoController.cs            (NEW)

src/tests/TeamsISO.Engine.Tests/
├── Pipeline/NdiReceiverTests.cs    (NEW)
├── Pipeline/NdiSenderTests.cs      (NEW)
├── Pipeline/ExponentialBackoffTests.cs (NEW)
├── Pipeline/IsoPipelineTests.cs    (NEW)
├── Interop/NdiRuntimeProbeTests.cs (NEW)
└── Controller/IsoControllerTests.cs (NEW)
```

---

## Task 1: `NdiReceiver`

Receiver that wraps `INdiInterop.CaptureFrame` and pushes results into a `ChannelWriter<RawFrame>`. Exposes a `CaptureOnce` test seam mirroring `FrameProcessor.ProcessOnceAsync`. `RunAsync` is the production loop with `LongRunning` thread semantics.

TDD assertions:
- `CaptureOnce` writes a captured frame to the output channel; counter increments.
- `CaptureOnce` does nothing on null capture (timeout); counter does not change.
- `RunAsync` honors cancellation and disposes the receiver handle on exit.

Commit: `feat(pipeline): add NdiReceiver with channel-based output`

---

## Task 2: `NdiSender`

Sender that pulls from a `ChannelReader<ProcessedFrame>` and forwards to `INdiInterop.SendFrame`. `SendNextAsync` returns true if a frame was sent; false if the channel completed. `RunAsync` loops until cancellation.

TDD assertions:
- `SendNextAsync` forwards a frame to the interop and increments the sent counter.
- Returns `false` when channel completes.
- `RunAsync` honors cancellation and disposes the sender handle.

Commit: `feat(pipeline): add NdiSender with channel-based input`

---

## Task 3: `ExponentialBackoff`

Pure policy type. Given an attempt count, returns the next delay (1, 2, 4, 8, 16 s, capped at 30 s) and decides whether to give up after N consecutive failures (default 5).

TDD assertions:
- Sequence at attempts 1..5 is 1, 2, 4, 8, 16 seconds.
- `ShouldGiveUp` returns true after the 5th attempt.
- Cap: at attempt 7 the delay is 30 s, not 64.

Commit: `feat(pipeline): add ExponentialBackoff policy`

---

## Task 4: `NdiRuntimeProbe`

Reads the runtime version via `INdiInterop.GetRuntimeVersion()`, compares to an expected value (passed in by the engine for now; a real comparison against the SDK headers is Phase B-2). Returns either `Match` or `Mismatch` with both versions populated. The `IsoController` will surface `EngineAlert.NdiRuntimeMismatch` from a mismatch.

TDD assertions:
- Match when versions equal.
- Mismatch carries detected and expected.

Commit: `feat(interop): add NdiRuntimeProbe with version-mismatch result`

---

## Task 5: `IsoPipeline` core lifecycle

Owns one `NdiReceiver`, one `FrameProcessor`, one `NdiSender`, and the two channels between them. `StartAsync` creates the channels, instantiates the receiver/processor/sender, kicks off the three loops on long-running tasks. `StopAsync` cancels the token, awaits the loops, and disposes everything.

`IsoState` transitions: `Idle` → `Receiving` (after start) → `Sending` (after first send) → `NoSignal` (handled by FrameProcessor's slate path and exposed via Stats). On exception the loop transitions to `Error`.

The restart loop is in Task 6.

TDD assertions:
- Start transitions Idle → Receiving.
- Stop transitions back to Idle and disposes interop handles.
- Receiver/sender handles are created on Start, disposed on Stop.

Commit: `feat(pipeline): add IsoPipeline core lifecycle`

---

## Task 6: `IsoPipeline` restart loop

Wraps the running pipeline in a supervisory loop that catches unhandled exceptions, applies `ExponentialBackoff`, and either restarts or transitions to `Error` after exhausting retries. State observable updates accordingly.

TDD assertions (using a fault-injecting INdiInterop):
- Pipeline that fails once, then runs cleanly, restarts and ends up Sending.
- Pipeline that fails 5+ consecutive times transitions to Error and stays there.
- Backoff delays are honored (using a fake delay primitive for fast tests).

Commit: `feat(pipeline): add IsoPipeline restart supervisor with backoff`

---

## Task 7: `IIsoController` interface + `IsoController` implementation

The top-of-engine API the WPF host will bind to in Phase C.

Surface:
- `IObservable<IReadOnlyList<Participant>> Participants { get; }`
- `IObservable<EngineAlert> Alerts { get; }`
- `IsoHealthStats GetStats(Guid participantId)`
- `Task EnableIsoAsync(Guid participantId, string? customName, CancellationToken ct)`
- `Task DisableIsoAsync(Guid participantId, CancellationToken ct)`
- `Task SetGlobalSettingsAsync(FrameProcessingSettings settings, CancellationToken ct)`

Implementation owns: `ParticipantTracker`, `NdiDiscoveryService`, dictionary of `IsoPipeline`, the `ConfigStore`, the runtime probe.

TDD assertions:
- `EnableIsoAsync` creates and starts a pipeline; `DisableIsoAsync` stops and removes it.
- `SetGlobalSettingsAsync` persists via ConfigStore and applies to existing pipelines.
- Discovery events flow through to the participants observable.
- `NdiRuntimeProbe` mismatch surfaces an alert.

Commit: `feat(controller): add IIsoController and IsoController implementation`

---

## Task 8: Wrap-up & milestone tag

- Run full test suite, confirm all green.
- Confirm coverage threshold still ≥80%.
- Update `docs/superpowers/plans/_NEXT.md` to describe Phase B-2 (Windows-only).
- Tag `phase-b-1-complete`.

Commit: `chore: phase-b-1 milestone wrap-up`
Tag: `phase-b-1-complete`

---

## Self-review

**Spec coverage:** Spec §4 components NdiReceiver, NdiSender, IsoPipeline, IsoController — Tasks 1, 2, 5, 6, 7. Spec §6 error handling restart/backoff — Task 6. Spec §6 NDI runtime mismatch — Task 4 + Task 7. ConfigStore integration in IsoController — Task 7.

**Phase B-2 (deferred):** Real `NdiInteropPInvoke` shim, real `LibYuvFrameScaler`, console smoke runner, integration tests against NDI Test Pattern source. All require Windows + NDI runtime so they live in their own plan.

**Type consistency:** All new types reference Phase A types unchanged. `INdiInterop` surface is sufficient — no additions needed.

No issues to fix. Ready to execute.
