docs(r2-06): 0.2.0 DataType provisioning delta (upsert/retype) + HISTGW_BOOL_SANDBOX_TAG recipe (06/U-7)

docs/Historian.md

@@ -129,6 +129,35 @@ for this node), which is the signal to check that `ServerHistorian:Enabled=true`
 > so a HistoryRead on it runs to the full `CallTimeout` (~30 s) before erroring. Auto-provisioning on deploy
 > keeps freshly-historized tags from hitting that slow path. See the `CallTimeout` row above.
 
+### 0.2.0 DataType provisioning delta (archreview 06/U-7)
+
+`EnsureTags` is contract-documented (HistorianGateway 0.2.0) as an **upsert** — *"creates or updates
+historian tags according to the given definitions"* — that maps per-tag onto AVEVA's
+`HistorianClient.EnsureTagAsync(definition) -> bool`. It is **not idempotent** (not routed through the
+idempotent retry pipeline) and **not skip-if-exists**.
+
+The 0.1.0→0.2.0 client bump made `HistorianTagDefinition.DataType` **proto3-optional** (explicit presence).
+Under 0.1.0, the provisioner's `Boolean → Int1` mapping sent wire value `0`, indistinguishable from unset, so
+the gateway defaulted such tags to the SDK-default **Float**. Under 0.2.0 the same call carries explicit
+presence, so Boolean tags now provision as **Int1** (the pre-existing intent of `HistorianTypeMapper` — no
+mapper code change is needed or wanted). Consequences:
+
+1. **New Boolean tags provision correctly as Int1.** This is the fix arriving as a silent, zero-diff
+   semantic change from the bump.
+2. **Pre-bump Boolean tags exist historian-side as Float.** On the next deploy that dispatches provisioning
+   for such a tag, the gateway is asked (via the upsert) to update it to Int1. The AVEVA-side outcome of an
+   in-place analog retype is the one thing the contract does not pin; the candidate behaviors are
+   (i) **accepted with tag versioning** (history preserved under the old version, new writes under Int1),
+   (ii) **accepted as a plain retype**, or (iii) **rejected per-tag** → `TagOperationResult.Success=false`
+   → counted in the provisioner's `failed=N` dispatch tally. Only a live run distinguishes these — see the
+   **retype probe** (`EnsureTags_type_change_outcome_is_observable`) in the [Live /run gate](#live-run-gate).
+   *(This list is replaced with the observed answer after the first live run.)*
+3. **The failure mode is bounded and observable either way.** Provisioning is fire-and-forget and never
+   blocks/fails a deploy; a per-tag rejection surfaces only as the tally's `failed` count. Values written to
+   a still-Float tag by the recorder remain readable (Float supersets Int1's 0/1 range); nothing is lost
+   pending a reconcile. A bulk retype sweep is **not** done in code — assess via the probe first, then decide
+   whether reconciliation is a one-time operator action.
+
 ---
 
 ## HistoryRead behavior
@@ -350,7 +379,14 @@ AVEVA Historian behind it healthy. Set `ServerHistorian:Enabled=true` with the c
 least one historized Galaxy tag. The gate is operator-driven — it is not part of the local docker-dev rig.
 The gateway-backed driver also ships an env-gated live suite (`Category=LiveIntegration`); see the
 `HISTGW_GATEWAY_ENDPOINT` / `HISTGW_GATEWAY_APIKEY` / `HISTGW_TEST_TAG` / `HISTGW_WRITE_SANDBOX_TAG` /
-`HISTGW_ALARM_SOURCE` env vars (it skips cleanly when they are absent).
+`HISTGW_BOOL_SANDBOX_TAG` / `HISTGW_ALARM_SOURCE` env vars (it skips cleanly when they are absent).
+`HISTGW_BOOL_SANDBOX_TAG` (e.g. `HistGW.LiveTest.BoolSandbox`, a **dedicated** writable Boolean tag —
+never the shared Float write sandbox) drives the 0.2.0 Boolean `EnsureTags` leg
+(`EnsureTags_boolean_sandbox_provisions_as_Int1`) and the retype probe
+(`EnsureTags_type_change_outcome_is_observable`) that resolve the
+[0.2.0 DataType provisioning delta](#020-datatype-provisioning-delta-archreview-06u-7) open question. Running
+the full suite against a **0.2.0** gateway (all six tests, none skipped) also discharges 06/U-2's
+"full documented run" for the historian suite.
 
 See [AlarmHistorian.md](AlarmHistorian.md) for the alarm write path and
 [ServiceHosting.md](ServiceHosting.md) for the (external) HistorianGateway deployment.