teamsiso/docs/superpowers/plans/2026-05-07-teamsiso-phase-b-1-pipeline-orchestration.md

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.