dohertj2/histsdk
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Merge handoff-event-gate-refresh: event-row item reflects captured + v8 gate

Browse Source 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B6mcaT2PjRFKcogzp9UkfC
This commit is contained in:
Joseph Doherty
2026-06-23 09:15:03 -04:00
parent 8ad160b843 876cbc5d94
commit ea85ea248d
1 changed files with 25 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reverse-engineering/handoff.md
+25 -16
View File
@@ -38,18 +38,26 @@ reuses the proven 2020 WCF byte serializers/parsers unchanged inside protobuf
**Everything still open is gated — none is a pure-code task:** **Everything still open is gated — none is a pure-code task:**
1. **gRPC event ROW retrieval** (`ReadEventsAsync` #2) — chain + StartEventQuery 1. **gRPC event ROW retrieval** (`ReadEventsAsync` #2) — **CAPTURED + DIAGNOSED
work; `GetNextEventQueryResultBuffer` long-polls and returns zero rows. 2026-06-22 (merged `8ad160b`); remaining gate is now a scoped RE+impl effort,
**Re-characterized 2026-06-22: this is capture-gated, NOT server-gated.** The not a capture.** The `capture-event` harness scenario drove the stock 2023 R2
earlier "needs an event-bearing 2023 R2 server" assumption is **disproven** — client over an Event-type gRPC connection and captured it reading **50 events**
the live 2023 R2 server *is* event-bearing (SQL ground truth via the INSQL (the live server is event-bearing — SQL ground truth via the INSQL linked
linked server: `Runtime.dbo.Events` = 19,356 rows in the last 30 days / server: `Runtime.dbo.Events` = 19,356 rows/30d, 90,944/365d). Two gaps vs the
90,944 in 365 days), yet the **empty-filter** gRPC event query still yields SDK: **(a)** the working `StartEventQuery` request is **version 6** (byte 0 =
zero rows over that exact 30-day window and long-polls to the deadline. So `06` + a 5-byte trailing pad), the SDK sent v5 — **SHIPPED**
the gap is in the empty-filter request shape (filter / namespace / event-tag (`HistorianEventQueryProtocol` `version` param, default 5 = WCF; the gRPC
registration), not data availability. Needs a **fresh native gRPC orchestrator passes 6; golden-tested). **(b) the real gate:** rows flow only on
event-query capture** to see what the stock 2023 R2 client sends. Bounded an **Event-type connection**. The native `OpenConnection.openParameters` is
≤30s, throws on no-row. format **v8** with a `ConnectionType` byte (Event `01` / Process `02`) right
after `ClientType`; the SDK's **v6** Open2 buffer has no such field (it writes
`ClientType` then `ConnectionMode` back-to-back), so the read-capable v6
connection cannot be marked as Event. `ConnectionMode` is not the lever (2020
WCF events work at `0x402`). Making event rows flow needs the SDK to emit the
native v8 `OpenConnection` with `ConnectionType=Event` (and likely the
`ExchangeKey` cert auth path) — a substantial follow-on. Full evidence +
byte-level diagnosis: `docs/reverse-engineering/grpc-event-query-capture.md`.
Gated test still pins the no-row throw; bounded ≤30s.
2. **R4.3 active-SF magnitude** — needs an **SF-active server** (D2 storage-engine 2. **R4.3 active-SF magnitude** — needs an **SF-active server** (D2 storage-engine
console handle). console handle).
3. **SendEvent over gRPC** — **capture-gated**: no distinct RPC, framing uncaptured. 3. **SendEvent over gRPC** — **capture-gated**: no distinct RPC, framing uncaptured.
@@ -67,10 +75,11 @@ reuses the proven 2020 WCF byte serializers/parsers unchanged inside protobuf
8. **Deferred-by-design** items (`write-commands` D1–D3, non-analog tag create, 8. **Deferred-by-design** items (`write-commands` D1–D3, non-analog tag create,
etc.) — bounded out until an explicit customer/user demand signal. etc.) — bounded out until an explicit customer/user demand signal.
To move any remaining item you need a **fresh native capture** (gRPC event-query To move any remaining item you need a **scoped RE+impl effort** (the v8
empty-filter framing — item 1; SendEvent gRPC framing — item 3), a **different Event-type `OpenConnection` — item 1, already captured + diagnosed), a **fresh
server** (SF-active for item 2), or a **demand signal** to unlock a deferred native capture** (SendEvent gRPC framing — item 3), a **different server**
item. Live-server gRPC probe recipe: set (SF-active for item 2), or a **demand signal** to unlock a deferred item.
Live-server gRPC probe recipe: set
`HISTORIAN_GRPC_HOST`/`_PORT 32565`/`_TLS true`/`_DNSID` + domain creds (strip `HISTORIAN_GRPC_HOST`/`_PORT 32565`/`_TLS true`/`_DNSID` + domain creds (strip
quotes — `reference_wonder_sql_vd03_credentials`) and run the gated quotes — `reference_wonder_sql_vd03_credentials`) and run the gated
`HistorianGrpcIntegrationTests`. `HistorianGrpcIntegrationTests`.