docs: strip task-tracking IDs from code comments and fill missing XML docs
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m16s
ci / java (push) Successful in 2m5s
ci / portable (push) Failing after 5m9s

Tracking IDs are review bookkeeping that rots in shipped source; the rationale they tagged is kept. Comment-only change (CommentChecker 458 -> 16 false positives).
This commit is contained in:
Joseph Doherty
2026-10-07 15:34:32 -04:00
parent f2e0861709
commit f40409a688
115 changed files with 549 additions and 411 deletions
@@ -43,7 +43,7 @@ public sealed class WorkerPipeSession
// The transport the reader and writer share, when this session was handed one to own. Null for
// the reader/writer constructors, whose callers keep ownership of whatever streams they built the
// pair over. Owning it is what lets teardown close the handle (WRK-31): on net48 a pipe read
// pair over. Owning it is what lets teardown close the handle: on net48 a pipe read
// parked in the kernel cannot be cancelled, only unblocked by disposal.
private readonly Stream? _transportStream;
@@ -175,7 +175,7 @@ public sealed class WorkerPipeSession
// Closing the transport is what actually ends a pipe read parked in the kernel: on net48
// NamedPipeClientStream.ReadAsync ignores its CancellationToken, so the message loop's
// cancellation can never reach one (WRK-31). It is deliberately the LAST teardown step,
// cancellation can never reach one. It is deliberately the LAST teardown step,
// because in the ordinary case every frame this session will ever write has been written
// AND flushed by the time control reaches here: WorkerFrameWriter.WriteAsync signals only
// after both, and each exit path awaits its final write before unwinding — the shutdown
@@ -563,7 +563,7 @@ public sealed class WorkerPipeSession
/// task eventually faults, so a task nobody is awaiting any more can never reach the
/// finalizer with an unobserved exception. Mirrors the shape
/// <c>WorkerFrameWriter.ObserveAbandonedFault</c> uses for frames a cancelled caller stops
/// awaiting (NEXT-04). Faulting is the only outcome that runs the continuation, and the
/// awaiting. Faulting is the only outcome that runs the continuation, and the
/// continuation is scheduled inline, so this costs nothing on the ordinary path.
/// </summary>
/// <param name="task">Task that may fault after its awaiter has walked away.</param>
@@ -614,7 +614,7 @@ public sealed class WorkerPipeSession
}
// Submit the whole drained batch through the writer's batch entry point under one lock
// acquisition so the burst pays a single flush instead of one per event (WRK-25). Events
// acquisition so the burst pays a single flush instead of one per event. Events
// are the low-priority frame class: the writer holds them behind any pending control frame
// (reply, fault, heartbeat, shutdown ack) so those are not delayed behind an event backlog,
// and intra-batch order is preserved.
@@ -634,7 +634,7 @@ public sealed class WorkerPipeSession
when (exception.ErrorCode == WorkerFrameProtocolErrorCode.MessageTooLarge)
{
// A single oversized event surfaces from the batch's awaited completions; the death is
// still IPC-30's structured, event-naming fault. Map the rejection back to the first
// still the structured, event-naming fault. Map the rejection back to the first
// event in batch order whose envelope overshoots the negotiated maximum — the same
// frame the writer rejected first.
await FaultOnOversizedEventAsync(
@@ -665,8 +665,8 @@ public sealed class WorkerPipeSession
}
/// <summary>
/// Ends the session on an event that cannot be framed, but deliberately and diagnosably
/// (IPC-30). An event above the negotiated frame maximum is undeliverable end to end — the
/// Ends the session on an event that cannot be framed, but deliberately and diagnosably.
/// An event above the negotiated frame maximum is undeliverable end to end — the
/// pipe maximum sits only an envelope reserve above the public gRPC cap — so dropping it
/// would silently make the event stream unfaithful, and synthesizing a placeholder is barred
/// by the no-synthesized-events rule. Instead the worker records which event blocked (never
@@ -869,7 +869,7 @@ public sealed class WorkerPipeSession
/// overshot the frame maximum. The fallback itself is a handful of bytes, so it fits any
/// sane negotiated maximum; the only way it can also throw <c>MessageTooLarge</c> is a
/// pathologically tiny negotiated maximum below the gateway's validation floor — the
/// pre-existing WRK-24 gap, which adds the negotiated-max lower bound that makes this
/// pre-existing gap, which adds the negotiated-max lower bound that makes this
/// unreachable. Until then, a defensive swallow keeps the "no diagnostics command is
/// session-fatal" invariant true even in that degenerate config: the correlation goes
/// unanswered and the gateway's own per-command timeout covers it, but the session lives.
@@ -1028,7 +1028,7 @@ public sealed class WorkerPipeSession
/// <c>MxCommandReply</c> does not stop at the pipe: the gateway returns it verbatim through
/// <c>Invoke</c>, where the public gRPC send cap applies, and the gateway's validator
/// couples the two limits so the pipe maximum never exceeds the gRPC cap by more than two
/// reserves (IPC-33). Subtracting both therefore keeps the packed events at or below the
/// reserves. Subtracting both therefore keeps the packed events at or below the
/// gRPC cap and leaves the wrapper — correlation id, protocol status, kind, the
/// <c>drain_events</c> length prefix and, in the truncated case, the
/// <c>DiagnosticMessage</c> — a full reserve of margin under it. Budgeting against the pipe
@@ -1246,8 +1246,8 @@ public sealed class WorkerPipeSession
_activeCommandTasks.Add(commandTask);
}
// WRK-33: every other discarded task in this file is wrapped with ObserveFaultWhenever
// (NEXT-04 discipline) so a fault reaching the finalizer unobserved is impossible. This
// Every other discarded task in this file is wrapped with ObserveFaultWhenever
// (the fault-observation discipline) so a fault reaching the finalizer unobserved is impossible. This
// wrapper task was the one exception — ObserveCommandTaskAsync only swallows
// OperationCanceledException, so any other exception escaping ProcessCommandAsync's own
// catch path (e.g. a future edit, or a failure past TryWriteFaultAsync's narrow filter)
@@ -1380,7 +1380,7 @@ public sealed class WorkerPipeSession
if ((!string.IsNullOrEmpty(snapshot.CurrentCommandCorrelationId) || snapshot.StaCallInProgress)
&& staleFor <= _sessionOptions.HeartbeatStuckCeiling)
{
// A command is in flight, or an STA call outside the dispatcher (the alarm poll, WRK-27) is
// A command is in flight, or an STA call outside the dispatcher (the alarm poll) is
// executing, and we are still within the defensive suppression ceiling — the STA is busy
// doing that work, not hung. The next MarkActivity() in StaRuntime.ProcessQueuedCommands
// will refresh LastActivityUtc once the work returns, at which point this branch stops
@@ -1402,7 +1402,7 @@ public sealed class WorkerPipeSession
// the StaHung fault just sent. Without this the heartbeat loop keeps
// advertising a non-faulted state that contradicts the fault.
_state = WorkerState.Faulted;
// WRK-34: CommandMethod is a method-name field, not a correlation-id field, so a
// CommandMethod is a method-name field, not a correlation-id field, so a
// consumer reading it (dashboard, gateway logs) shouldn't see a bare correlation id
// there. Use a stable label and carry the stuck command's correlation id (if any) in
// the diagnostic message instead.