docs(code): honest rationales — Akka restart semantics, per-key shards, EF literal inlining; retire or annotate orphaned members

2026-08-16 05:33:33 -04:00
parent dbc9223206
commit b9e9df4081
11 changed files with 133 additions and 58 deletions
@@ -1491,8 +1491,15 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
        var sourceCode = Expression.Property(parameter, nameof(Script.SourceCode));
        var contains = typeof(string).GetMethod(nameof(string.Contains), [typeof(string)])!;

-        // Indexing a captured array (rather than Expression.Constant(path)) keeps EF parameterising each
-        // path instead of inlining it as a SQL literal, so the paths never reach the generated SQL text.
+        // Indexing an array (rather than Expression.Constant(path) directly) keeps the expression tree
+        // cache-friendly: every rename of the same path-count produces the same tree shape.
+        // ⚠️ It does NOT guarantee parameterisation. The array here is a constant with no closure over it,
+        // so EF may well inline each path into the SQL as an escaped literal — which is safe (EF escapes
+        // the Contains argument either way, so there is no injection surface) but means a rename can emit up
+        // to ScriptScanBatchSize (200) literals per batch and churn the plan cache. Whether the provider
+        // actually parameterises this shape is unverified: proving it needs a SQL-Server-backed test, not
+        // EF InMemory. Recorded in the follow-up register of
+        // docs/plans/2026-08-15-perf-roadmap-remainder.md.
        var values = paths.ToArray();
        Expression? body = null;
        for (var i = 0; i < values.Length; i++)