docs(src): fix CommentChecker findings across src/ — 1,032 → 5 (all false positives)

Comment/XML-doc changes only, no code logic:
- strip project-tracking references (WP*, P*-*, row-NN, #NN, Task N) from
  comments, keeping the explanatory rationale
- add missing summaries, <param>, <returns>, <typeparam> and <inheritdoc/>
- replace misused <inheritdoc/> with real docs; where <inheritdoc/> was
  combined with useful remarks, move the rationale into // comments
- drop stale replicationActor <param> on DeploymentManagerActor ctor

Remaining 5 are false positives (CWE-1236 x2, failures-1, year-0001, M365).
Build 0 errors / 0 warnings.
This commit is contained in:
Joseph Doherty
2026-10-07 14:12:25 -04:00
parent 3a217b9484
commit 0ffd4bdbea
217 changed files with 1224 additions and 695 deletions
@@ -190,6 +190,11 @@ public class ManagementActor : ReceiveActor
}
/// <summary>Audited database-only application boundary shared by UI and management envelopes.</summary>
/// <param name="services">Scoped service provider used to resolve handlers and repositories.</param>
/// <param name="command">The configuration command to execute.</param>
/// <param name="user">The authenticated user the command runs as.</param>
/// <param name="clientIp">Optional client IP address recorded in the audit entry.</param>
/// <returns>The command's result object, or <c>null</c> when the command produces none.</returns>
public static async Task<object?> ExecuteConfigurationCommandAsync(IServiceProvider services, object command, AuthenticatedUser user, string? clientIp = null)
{
if (!IsConfigurationCommand(command)) throw new ArgumentException("Not a configuration command.", nameof(command));
@@ -1496,8 +1501,8 @@ public class ManagementActor : ReceiveActor
// submit device writes to their permitted sites — same rule C2 applies to
// DeployArtifacts, on a higher-consequence path. Checked before the row exists.
//
// The unresolvable case is fail-CLOSED and answered BEFORE the "not found"
// (arch-review 2026-08-19 P6-5): resolving first and reporting not-found made
// The unresolvable case is fail-CLOSED and answered BEFORE the "not found":
// resolving first and reporting not-found made
// this handler a site-identifier existence oracle for an out-of-scope caller,
// who now gets the same scope denial whether or not the site exists.
var siteRepo = sp.GetRequiredService<ISiteRepository>();
@@ -1560,7 +1565,7 @@ public class ManagementActor : ReceiveActor
// the row's target site — checked BEFORE the TTL/self-approval/CAS chain so an
// out-of-scope verifier can neither consume the Pending transition nor relay.
//
// It is also checked BEFORE the status test (arch-review 2026-08-19 P6-5): the
// It is also checked BEFORE the status test: the
// "is 'Executed', not Pending" message told an out-of-scope caller both that the
// id existed and what had happened to it. An out-of-scope caller now gets the
// same scope denial for every id, existing or not.
@@ -1701,7 +1706,7 @@ public class ManagementActor : ReceiveActor
row.ExecutionError = error;
// UpdateAsync overwrites all columns -> pass the fully-populated entity.
// Safe as a blind write (arch-review 2026-08-19 P6-1): winning the
// Safe as a blind write: winning the
// Pending->Approved CAS above gives this leg EXCLUSIVE ownership of the row from
// that point on. Every other writer transitions only out of Pending —
// TryMarkApprovedAsync, TryMarkRejectedAsync and TryMarkExpiredAsync (both the
@@ -1738,8 +1743,7 @@ public class ManagementActor : ReceiveActor
// Site scope (arch-review R2 N3): the rejecting Verifier must be permitted on
// the row's target site — checked BEFORE the TTL/self-approval chain, and (as on
// approve) BEFORE the status test, so the not-found/status errors stop being an
// existence-and-status oracle for an out-of-scope caller (arch-review 2026-08-19
// P6-5). The CAS below is unchanged.
// existence-and-status oracle for an out-of-scope caller. The CAS below is unchanged.
await EnforceSiteScopeForIdentifier(sp, user, entity.SiteId);
if (!string.Equals(entity.Status, "Pending", StringComparison.Ordinal))
@@ -1759,7 +1763,7 @@ public class ManagementActor : ReceiveActor
"A secured write cannot be verified by its submitter.");
// Compare-and-swap: guards the approve-vs-reject race exactly as approve's own
// CAS guards the two-verifier race (arch-review 2026-08-19 P6-1). The status
// CAS guards the two-verifier race. The status
// check above is a stale read — commands run concurrently, each on its own DI
// scope and across both central nodes on one shared MS SQL — so a concurrent
// approve can win its CAS and enter its multi-second WriteTagAsync relay in the
@@ -2003,8 +2007,8 @@ public class ManagementActor : ReceiveActor
/// Lists data connections, constrained to the caller's permitted sites.
/// </summary>
/// <remarks>
/// Arch-review 2026-08-19 P6-4. The list used to take no user at all and return
/// EVERY site's connections, which nullified the row-98 fail-closed gate on
/// The list used to take no user at all and return
/// EVERY site's connections, which nullified the fail-closed gate on
/// <see cref="HandleGetDataConnection"/> — Get denied exactly what List handed
/// over, and the secret-elided <see cref="DataConnectionPublicShape"/> still
/// leaked site topology plus an id-existence oracle. Scoping now mirrors
@@ -3872,7 +3876,7 @@ public class ManagementActor : ReceiveActor
private static async Task<object?> HandleDebugSnapshot(IServiceProvider sp, DebugSnapshotCommand cmd, AuthenticatedUser user)
{
// Fail-CLOSED before the not-found (arch-review 2026-08-19 P6-5): reporting
// Fail-CLOSED before the not-found: reporting
// "Instance {id} not found" ahead of the scope check made this handler an
// instance-id existence oracle for an out-of-scope caller. The scope denial is
// now the same answer whether or not the instance exists.