docs(plan): Galaxy writer/subscription-registry item-handle sharing design

2026-06-18 04:11:24 -04:00
parent 70e1bde90f
commit c85c4e5cd0
1 changed files with 138 additions and 0 deletions
@@ -0,0 +1,138 @@
 # Galaxy writer ⇄ subscription-registry item-handle sharing — Design
 > Brainstormed 2026-06-18. Backlog item: `stillpending.md` §2.4 — "Galaxy — writer
 > item-handle cache not shared with the subscription registry"
 > (`Driver.Galaxy/Runtime/GatewayGalaxyDataWriter.cs`). Off master `70e1bde9`.
 ## Problem (verified in code)
 The Galaxy data writer's item-handle cache is **already shipped and reconnect-wired**:
 `GatewayGalaxyDataWriter` holds `_itemHandles` (fullRef → MXAccess hItem) plus
 `_supervisedHandles`, and `GalaxyDriver.ReopenAsync` invalidates them after a session
 recreate (`GalaxyDriver.cs:298`, commits `f05b5d79` / `f77488ee`). So "add a writer cache"
 is **not** the open work.
 What is open is exactly what the backlog says: the writer cache is **isolated from the
 `SubscriptionRegistry`**. The registry already records `TagBinding(FullReference, ItemHandle)`
 for every live subscription, and — the load-bearing fact — both subscribe-handles (from
 `SubscribeBulk`) and write-handles (from the writer's `AddItem`) are issued against the **same
 MXAccess server registration** (`GalaxyMxSession.ServerHandle`). Within one registration an
 hItem is shared across the AddItem / Advise / Write call paths, so a handle the gateway returned
 for a subscription is reusable by a `Write`.
 Today the writer never consults the registry, so the **first write to an already-subscribed tag
 pays a redundant `AddItem` round-trip** (subsequent writes hit the writer's own `_itemHandles`).
 This is an `_Optimization._` — a first-write-only latency saving, plus unification of handle
 provenance (one fewer source of truth for "which hItem is this tag").
 ## Load-bearing premise (proven live, not assumed)
 > *A subscription's item handle is usable for a no-login supervisory `Write` that commits.*
 If this were false, borrowing the subscribed handle would **regress writes** for subscribed
 tags. The MXAccess Toolkit semantics say it holds (one hItem per item under a registration,
 shared across Advise/Write), but this phase does **not** assume it — the live-gw test is the
 **merge gate**, not decoration.
 ## Approach
 Three options were considered:
 1. **Delegate seam (chosen).** The writer ctor gains an optional
   `Func<string, int?>? subscribedHandleSource = null`; `GalaxyDriver` wires it to the
   registry's new `TryResolveItemHandle`. This is symmetric with the writer's existing
   `securityResolver` delegate, preserves the writer's "independently testable" property
   (`null` ⇒ today's exact behavior), and is the smallest surface.
 2. **Direct `SubscriptionRegistry` reference** in the writer. Same assembly, registry is
   test-constructible — but couples the writer to a concrete collaborator with no upside over (1).
 3. **Unified shared cache object** both sides read/write. Matches the literal "wire bindings
   into `_itemHandles`" phrasing but is the most invasive (changes the writer's ownership
   model). YAGNI.
 → **Approach 1.** AdminUI untouched. No Commons/proto/EF/migration change. No bUnit.
 ## Resolution rule (self-healing — no stale-handle regression)
 `GatewayGalaxyDataWriter.EnsureItemHandleAsync(fullRef)` becomes:
 1. `_itemHandles` hit (the writer `AddItem`'d this tag itself before) → use it.
 2. else `subscribedHandleSource?.Invoke(fullRef)` returns a **live** handle → use it, but
   **do NOT store it in `_itemHandles`**. The registry owns the borrowed handle's lifecycle
   (including reconnect `Rebind`), so after a reconnect the writer always re-borrows the *fresh*
   handle on the next write — there is no stale-cache window introduced by the borrow.
 3. else `AddItem` + store in `_itemHandles` (today's path), incrementing an `AddItemCallCount`
   test seam.
 `AdviseSupervisory` is unchanged: the writer still supervisory-advises the (possibly borrowed)
 hItem once per handle via `_supervisedHandles`. Borrowing only skips the `AddItem` round-trip —
 which is the entire point of the optimization. The borrowed item already carries the
 subscriber's data-change advise; supervisory advise is an additional mode on the same item.
 The decision in steps 1–2 is extracted into a synchronous internal seam
 `TryResolveCachedOrBorrowed(fullRef) -> int?` so it is unit-testable **without a live session**
 (the SDK `MxGatewaySession` is sealed with an internal ctor and cannot be faked — see Testing).
 `EnsureItemHandleAsync` calls the seam first and only `AddItem`s on a null result.
 ## Registry change
 `SubscriptionRegistry` gains a forward lookup:
 - A `ConcurrentDictionary<string, int> _itemHandleByFullRef` (`StringComparer.OrdinalIgnoreCase`,
  matching the writer's cache), maintained incrementally in `Register` / `Rebind` (add the
  `fullRef → handle` for each `binding.ItemHandle > 0`) and best-effort dropped in `Remove` /
  `Rebind`.
 - `public int? TryResolveItemHandle(string fullRef)` that returns the mapped handle **only if
  `_subscribersByItemHandle` still contains it** — a liveness guard. This means even a lingering
  forward-map entry can never hand out a dead handle, because `_subscribersByItemHandle` is the
  already-authoritative live-handle set. The guard de-risks the removal bookkeeping: the forward
  map is an index, not the source of truth.
 The event-dispatch hot path (`ResolveSubscribers`) is **untouched** — the forward map is consulted
 only on writes (rare relative to events) and mutated only on subscribe/unsubscribe/rebind (which
 already do O(bindings) work).
 `GalaxyDriver` passes `_subscriptions.TryResolveItemHandle` as the writer's
 `subscribedHandleSource` when it constructs the production writer.
 ## Error handling
 Unchanged. A borrowed handle that fails a write surfaces its own Bad status via the existing
 `TranslateReply` path; the writer does not cache borrowed handles, so the next write simply
 re-resolves (re-borrow if still live, else `AddItem`). `TryResolveItemHandle` returns `null`
 cleanly for unknown / dead handles.
 ## Testing
 **Unit (xUnit + Shouldly, `Driver.Galaxy.Tests`) — no live session required:**
 - `GatewayGalaxyDataWriter`: seed `subscribedHandleSource` → `TryResolveCachedOrBorrowed`
  returns the borrowed handle and leaves `CachedItemHandleCount == 0`; a `_itemHandles` hit wins
  over the source; a `null` source ⇒ no borrow (returns null). (Mirrors the existing
  `SeedHandleCachesForTest` / count-seam pattern, since the gw session cannot be faked.)
 - `SubscriptionRegistry`: `TryResolveItemHandle` returns the handle after `Register`; returns
  `null` after `Remove`; returns the **fresh** handle after `Rebind`; the liveness guard returns
  `null` when the handle is absent from `_subscribersByItemHandle`.
 **Live gw (the merge gate)** — extend `GatewayGalaxyLiveReopenAndWriteTests` (skip-gated; runs
 against `MXGW_ENDPOINT=http://10.100.0.48:5120` with the key sourced via the durable
 `docker exec … printenv GALAXY_MXGW_API_KEY` recipe, never echoed). Add an internal
 `AddItemCallCount` seam on the writer, then:
 - Subscribe a real tag (registry now holds its hItem) → write it through the registry-wired
  writer → assert the write **commits** (Good status + value persists) **and `AddItemCallCount == 0`**.
 - Control: write a **non-subscribed** tag → assert `AddItemCallCount == 1`.
 This proves both halves: the borrowed handle is write-usable (premise holds) **and** the redundant
 `AddItem` is actually skipped.
 ## Deferred / out of scope
 - Reverse direction (subscriber borrowing the writer's `AddItem` handles) — subscriber handles
  come from `SubscribeBulk`; no need.
 - Unifying the two caches into one shared object (Approach 3).
 - Any AdminUI / Commons / proto / EF change.
 ## Done =
 Build clean + `dotnet test` (Driver.Galaxy) green + the live-gw test proves a subscribed-tag
 write commits with zero `AddItem` → merge to master + push.