feat(wire): attribute updates carry source_execution_id/trace; PullTraceEvents RPC + site read-by-execution-ids

Flow Debugger (design 2026-09-05 §5.3/§5.4): AttributeValueUpdate fields 7/8 stamped by StreamRelayActor and parsed by SiteStreamGrpcClient (older frames => null/false). New PullTraceEvents unary RPC on SiteStreamService (same PSK-gated prefix as PullAuditEvents): a point read of the site audit SQLite by ExecutionId OR ParentExecutionId (ISiteAuditQueue.ReadByExecutionIdsAsync, json_extract on the codec's camelCase keys, new IX_audit_event_occurred index, 64-id / 2000-row caps) that moves no cursor and flips no ForwardState. Central IPullTraceEventsClient/GrpcPullTraceEventsClient mirror the audit pull client (endpoint resolution, NodeB failover, fault => empty) and register beside it. Claude-Session: https://claude.ai/code/session_01GSLkkHKz9JrAtmJjmQK3cP
2026-09-05 23:52:50 -04:00
parent f15d0db0ad
commit 7e61552d82
15 changed files with 1458 additions and 80 deletions
@@ -265,6 +265,12 @@ public class SqliteAuditWriter : IAuditWriter, ISiteAuditQueue, IAsyncDisposable
            -- four reads + the backlog COUNT/MIN.
            CREATE INDEX IF NOT EXISTS IX_fwd
                ON audit_forward_state (ForwardState, IsCachedKind, OccurredAtUtc);
+
+            -- Flow Debugger (design 2026-09-05 §5.4): PullTraceEvents reads audit_event by
+            -- time window + json_extract on ExecutionId/ParentExecutionId; this bounds the scan
+            -- to the window. Additive and idempotent.
+            CREATE INDEX IF NOT EXISTS IX_audit_event_occurred
+                ON audit_event (OccurredAtUtc);
            """;
        cmd.ExecuteNonQuery();
    }
@@ -848,6 +854,71 @@ public class SqliteAuditWriter : IAuditWriter, ISiteAuditQueue, IAsyncDisposable
        }
    }

+    /// <summary>Flow Debugger PullTraceEvents: hard cap on ids per read (design §5.4).</summary>
+    public const int MaxExecutionIdsPerRead = 64;
+
+    /// <inheritdoc />
+    public Task<IReadOnlyList<AuditEvent>> ReadByExecutionIdsAsync(
+        IReadOnlyCollection<Guid> executionIds, DateTime sinceUtc, int limit, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(executionIds);
+        if (limit <= 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(limit), "limit must be > 0.");
+        }
+        if (executionIds.Count == 0)
+        {
+            return Task.FromResult<IReadOnlyList<AuditEvent>>(Array.Empty<AuditEvent>());
+        }
+        if (executionIds.Count > MaxExecutionIdsPerRead)
+        {
+            throw new ArgumentOutOfRangeException(nameof(executionIds),
+                $"at most {MaxExecutionIdsPerRead} execution ids per read.");
+        }
+
+        // Flow Debugger (design 2026-09-05 §5.4): a POINT read independent of the forwarding
+        // sidecar — a traced row is served whether Pending, Forwarded or Reconciled, and
+        // serving it moves no cursor. DetailsJson is the codec's camelCase JSON, so the paths
+        // are $.executionId / $.parentExecutionId; ids are stored in "D" form.
+        lock (_readLock)
+        {
+            ObjectDisposedException.ThrowIf(_disposed, this);
+
+            using var cmd = _readConnection.CreateCommand();
+            var names = new List<string>(executionIds.Count);
+            var i = 0;
+            foreach (var id in executionIds)
+            {
+                var name = $"$e{i++}";
+                names.Add(name);
+                cmd.Parameters.AddWithValue(name, id.ToString("D"));
+            }
+            var inList = string.Join(", ", names);
+
+            cmd.CommandText = $"""
+                SELECT EventId, OccurredAtUtc, Actor, Action, Outcome,
+                       Category, Target, SourceNode, CorrelationId, DetailsJson
+                FROM   audit_event
+                WHERE  OccurredAtUtc >= $since
+                  AND  (json_extract(DetailsJson, '$.executionId') IN ({inList})
+                        OR json_extract(DetailsJson, '$.parentExecutionId') IN ({inList}))
+                ORDER  BY OccurredAtUtc ASC, EventId ASC
+                LIMIT  $limit;
+                """;
+            cmd.Parameters.AddWithValue("$since", EnsureUtc(sinceUtc).ToString(
+                "o", System.Globalization.CultureInfo.InvariantCulture));
+            cmd.Parameters.AddWithValue("$limit", limit);
+
+            var rows = new List<AuditEvent>(Math.Min(limit, 256));
+            using var reader = cmd.ExecuteReader();
+            while (reader.Read())
+            {
+                rows.Add(MapRow(reader));
+            }
+            return Task.FromResult<IReadOnlyList<AuditEvent>>(rows);
+        }
+    }
+
    /// <summary>
    /// Highest <c>audit_forward_state.rowid</c> this instance has ever SERVED from
    /// <see cref="ReadPendingSinceAsync"/> — i.e. the insertion-order high-water mark of