docs(historian): QuestDB backend documentation (as built)

Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe

docs/plans/2026-10-10-questdb-historian-design.md

@@ -1,6 +1,7 @@
 # QuestDB historian backend — design
 
-**Status:** approved section by section on 2026-10-10. Gitea #666.
+**Status:** approved section by section on 2026-10-10. Gitea #666. **As-built pass (T8, 2026-10-11):** every section below was re-checked against
+the merged code; where the two disagreed the text was corrected inline and marked **(as built)**. User documentation: `docs/Historian.md` §"QuestDB backend".
 **Builds on:** `docs/plans/2026-10-09-pluggable-historian-design.md`, which defines the provider seam, typed values, the
 HistoryUpdate service and the SQL Server backend, all merged to master as `8ec7a83c`.
 
@@ -12,7 +13,7 @@ HistoryUpdate service and the SQL Server backend, all merged to master as `8ec7a
 | Write path | **Postgres wire protocol only, via `Npgsql`.** It is already centrally pinned at 10.0.3. No ILP, no new NuGet package. |
 | Retention | **Included.** `RetentionDays` is applied as table TTL. QuestDB drops expired day partitions itself. |
 | Approach | **B: shared dialect-free core plus per-backend SQL.** The pure logic moves out of the SQL Server backend into `Driver.Historian.Sql.Common`. One conformance suite runs against both backends. |
-| Timestamps | **Microseconds.** Postgres-wire timestamps are microsecond resolution, and real source timestamps are at best milliseconds. Two samples less than 1 µs apart within a batch collapse to one, and the first wins. This is documented. |
+| Timestamps | **Microseconds.** Postgres-wire timestamps are microsecond resolution, and real source timestamps are at best milliseconds. Two samples less than 1 µs apart collapse to one, and the first wins — within a batch, and also against an already-stored row (the existence check runs on the rounded time). This is documented. |
 
 Out of scope:
 - event HistoryUpdate;
@@ -62,8 +63,12 @@ seam classes, all calling the shared core.
 | `QuestDbConnection` | Npgsql `NpgsqlDataSource` (pooled), command timeouts, transient-error classification, UTC timestamp reads. |
 | `QuestDbSchemaBootstrapper` | Idempotent `CREATE TABLE IF NOT EXISTS` for the three tables, then applies TTL. It is concurrency-safe across two nodes starting together, and caches a failure for 5 s. |
 | `QuestDbHistorianValueWriter` | `IHistorianValueWriter` for live samples (§2.2). |
-| `QuestDbTagProvisioner` | `IHistorianProvisioning`: upserts `hist_tag` rows. |
-| `QuestDbAlarmHistorianWriter` | `IAlarmHistorianWriter`: writes events with the deterministic SHA-256 `event_id` and the same classify rules as SQL Server (unknown ⇒ RetryPlease). |
+| `QuestDbTagCatalog` | **(as built)** The only "is this tag known" authority (R7): a `hist_tag` row, positive results cached. Reads never create a tag; the live writer and HistoryUpdate Insert/Update do (Replace and the deletes do not). Re-inserting a known tag is skipped, because the dedup upsert would erase the unit and description the provisioner wrote. |
+| `QuestDbWalVisibility` | **(as built)** The read-your-writes wait (§2.3), used by every write path. |
+| `QuestDbTimeClusters` | **(as built)** Groups request times into ranges (gap > 1 min starts a new one) so existence reads are one range query per cluster. |
+| `QuestDbTables`, `QuestDbAggregateQueries` | **(as built)** DDL / TTL helpers, and the push-down aggregate SQL (§3). |
+| `QuestDbTagProvisioner` | `IHistorianProvisioning`: upserts `hist_tag` rows in chunks; **(as built)** a request without a unit or description keeps the stored one. |
+| `QuestDbAlarmHistorianWriter` | `IAlarmHistorianWriter`: **(as built)** one INSERT per event (not batched), with the deterministic SHA-256 `event_id`. Outcomes: Ack; `RetryPlease` for transient and unclassified errors; `PermanentFail` only for a pre-1970 time or a server message naming an inconvertible / out-of-range / too-long / null value. |
 | `QuestDbHistorianDataSource` | `IHistorianDataSource` (§3), with QuestDB SQL for raw, at-time, events and bucket statistics. |
 | `QuestDbHistorianDataUpdater` | `IHistorianDataUpdater` (§2.3), the soft-delete updater. |
 | `QuestDbHistorianProvider` | `IHistorianBackendProvider`: `Name = "QuestDb"`, `SupportedKinds` = all six (FrozenSet), one shared connection and bootstrapper. |
@@ -73,6 +78,8 @@ Host changes:
 - `ServerHistorianOptionsValidator` validates the QuestDb section, gated on consumers, the same way it gates
   SqlServer.
 - `Host.csproj` gets a ProjectReference.
+- **(as built)** `IHistorianDataSource` gains the default member `TimestampResolutionTicks` (1; QuestDB 10), and the node manager's Raw paging steps off a drained timestamp by it (§3).
+- **(as built)** The provider builds its shared pieces (connection, bootstrapper, catalog, WAL wait) on the first `Create*` call, not in the constructor, so a provider nobody consumes never fails on its options.
 
 ## 2. Schema and writes
 
@@ -132,11 +139,11 @@ Column details (**T0-confirmed**):
   - `long.MinValue` (LONG) and `int.MinValue` (INT) are QuestDB's NULL sentinels.
   - `BYTE` and `BOOLEAN` have **no NULL**: unset or DBNull reads `0` / `false`. So `deleted` defaults to `false`, and a
     LEFT-JOINed "no row" yields `kind = 0`. Absence must be detected on a NULL `ts`, not on `kind`.
-- **Ruling candidate (T0):** an Int64 sample of exactly `long.MinValue` stores `int_value` as NULL. The QuestDB read
+- **Ruling RC2 (as built):** an Int64 sample of exactly `long.MinValue` stores `int_value` as NULL. The QuestDB read
   path repairs it before the shared `FromColumns`: `kind = Int64 ∧ int_value IS NULL ∧ num_value = -2^63` ⇒
   `long.MinValue`. That double is exact. Without the repair the sample would be served as 0.
 - A designated timestamp **before 1970-01-01 cannot be inserted** (`designated timestamp before 1970-01-01 is not
-  allowed`). See §2.2.
+  allowed`). See §2.2 (RC1).
 - Tag names: SYMBOL and VARCHAR take 400 characters (non-ASCII included). SYMBOL grows past its capacity hint
   (16,384) with no error, and was tested with 30,000 distinct tags. No `CAPACITY` clause is needed.
 
@@ -144,20 +151,24 @@ Column details (**T0-confirmed**):
 
 1. Group the batch by tag and remove duplicates within the batch. **The first value wins.** A timestamp is rounded
    to microseconds before this step, so microsecond collisions also collapse.
-2. For each tag, fetch the timestamps that already exist in the batch's `[min ts, max ts]` range. **Tombstones are
-   included**, so a re-sent outbox batch can never resurrect a deleted row or overwrite a HistoryUpdate change.
-   T0-confirmed form (Q11): `SELECT ts FROM {p}sample WHERE tag = $1 AND ts >= $2 AND ts <= $3`, with no `NOT
-   deleted`, followed by a client-side set test.
+2. For each tag, fetch the timestamps that already exist. **(as built)** The batch's times are grouped into clusters
+   (`QuestDbTimeClusters`: a gap over 1 minute starts a new range; the live writer also caps a range at 1,000 times), with one range query per cluster, so one
+   far-away outlier does not widen a single query over every stored row in between. **Tombstones are included**, so a re-sent
+   outbox batch can never resurrect a deleted row or overwrite a HistoryUpdate change. T0-confirmed form (Q11): `SELECT ts
+   FROM {p}sample WHERE tag = $1 AND ts >= $2 AND ts <= $3`, with no `NOT deleted`, followed by a client-side set test. The tag is
+   registered in `QuestDbTagCatalog` first (a write creates an unknown tag).
 3. Insert only the new rows with parameterised multi-row `INSERT … VALUES (…),(…)`, **at most 1,000 rows per
    statement** (T0-confirmed Q2). QuestDB reads the Bind parameter count as a signed int16, so the hard limit is
-   32,767 parameters (3,640 nine-column rows). Within one statement a duplicate key keeps the **last** row, which is
+   32,767 parameters. **(as built)** The live writer binds 8 parameters per row (`deleted` is the literal `false`; 4,095 rows
+   would fit), the updater 9 (3,640 rows). Within one statement a duplicate key keeps the **last** row, which is
    why step 1's "first wins" is done client-side.
 4. Stored-value rules are shared with SQL Server:
    - NaN/±Inf, or any Empty with a non-Bad status, is stored Empty with `BadOutOfRange` or `BadNoData`.
    - Comms-loss outage markers are stored as given.
    - A tag name over 400 characters is a per-tag failure.
-   - **Ruling candidate (T0 Q13):** a sample timestamped before 1970-01-01 cannot be stored, because QuestDB rejects
-     the whole INSERT. The writer drops such samples before the INSERT and logs one Warning per batch. A retry could
+   - **Ruling RC1 (T0 Q13):** a sample timestamped before 1970-01-01 cannot be stored, because QuestDB rejects
+     the whole INSERT. The writer drops such samples before the INSERT, logs one Warning per batch and counts them
+     (`DroppedPre1970`); the call still succeeds for the rest. A retry could
      never succeed, and sending the sample would push the tag's whole group into the #538 quarantine.
 5. Any SQL or transport failure makes the write return `false`, so the recorder retries and the #538 per-tag
    quarantine still applies. It never throws.
@@ -166,7 +177,10 @@ The recorder is Primary-only (#537), so step 2 does not race another live writer
 visibility, bounded by `VisibilityTimeout` (plan R5), using the §2.3 wait.
 
 Binding (T0-confirmed Q1/Q6/Q13):
-- Every timestamp parameter is `NpgsqlDbType.TimestampTz` with `DateTimeKind.Utc`, after `Round`. `Timestamp` + `Utc`
+- Every timestamp parameter is `NpgsqlDbType.TimestampTz` with `DateTimeKind.Utc`, after `Round` (**as built:** Unspecified is
+  taken as UTC, Local is converted, then ticks are truncated to a multiple of 10). `BindTimestamp(…, clampToEpoch: true)` is used
+  only for write binds of a designated timestamp; read bounds are never clamped (a pre-1970 bound is valid, and clamping it would
+  move the bound across the epoch row). `Timestamp` + `Utc`
   throws in Npgsql. Npgsql truncates sub-µs ticks **toward 2000-01-01**, which rounds *up* before 2000. A raw
   `DateTime.MinValue`/`MaxValue` is sent as ±infinity, and a `[Min, Max)` range then silently matches nothing. R6's
   `BindTimestamp` (round; `MinValue` → `+10` ticks; `MaxValue` → `−9` ticks) fixes all three.
@@ -193,7 +207,7 @@ issued. "Exists" means a row that is present **and not deleted**.
 
 | Operation | Effect | Result |
 |---|---|---|
-| Insert | Write the row when none exists; a tombstone counts as absent | `GoodEntryInserted` / `BadEntryExists` |
+| Insert | Write the row when none exists; **a tombstone counts as absent, so Insert over a tombstone returns `GoodEntryInserted`** (an explicit client insert may re-populate a deleted time; only the live writer's redelivery is barred, §2.2) | `GoodEntryInserted` / `BadEntryExists` |
 | Replace | Overwrite the row when one exists | `GoodEntryReplaced` / `BadNoEntryExists` |
 | Update | Write the row either way | `GoodEntryReplaced` or `GoodEntryInserted` |
 | DeleteAtTime | Write a tombstone (`deleted = true`, value NULL) where a row exists | `Good` / `BadNoEntryExists` |
@@ -212,8 +226,12 @@ Further rules:
      target`. Stop early, with a Warning, if `suspended` is true. Stop at `VisibilityTimeout`.
   - Measured: median 0 ms, p95 6 ms, max 13 ms. Up to 7/20 inserts were not visible to an immediate re-read, so the
     wait is required. A concurrent writer can only raise `target`. The key-poll fallback (S11) is not used.
-- Existence checks for sparse item times (Insert/Replace/Update/DeleteAtTime) use `SELECT ts, deleted FROM {p}sample
-  WHERE tag = $1 AND ts IN ($2, …)`, chunked at 1,000 times (T0 Q11).
+- **(as built)** Existence checks for item times (Insert/Replace/Update/DeleteAtTime) are **not** `IN` lists: they use the T0 Q11 range
+  form, one query per `QuestDbTimeClusters` cluster, `SELECT ts FROM {p}sample WHERE tag = $1 AND ts >= $2 AND ts <= $3 AND NOT
+  deleted`, and the set test is client-side. The `IN ($2, …)` form this section originally proposed is not used.
+- **Unknown tag (as built):** Insert and Update register the tag in `QuestDbTagCatalog`; Replace and the deletes do not (Replace ⇒
+  `BadNoEntryExists`, DeleteAtTime ⇒ `BadNoEntryExists`, DeleteRaw ⇒ `BadNoData`).
+- **Tombstone shape (as built):** `kind = Empty (0)`, value columns NULL, `status = BadNoData`, `deleted = true`.
 - **DeleteRaw (T0-confirmed), page size 1,000:**
   1. `SELECT ts FROM {p}sample WHERE tag = $1 AND ts >= $2 AND ts < $3 AND NOT deleted ORDER BY ts LIMIT 1000`.
   2. Write one 1,000-row tombstone INSERT.
@@ -221,12 +239,17 @@ Further rules:
   4. Continue from `last ts + 10 ticks`, until a page comes back empty.
   The wait between pages is required, or the next page re-reads rows just tombstoned. Measured: 2,500 rows, 3 pages,
   103 ms.
-- **Ruling candidate (T0 Q13):** an Insert, Replace or Update item timestamped before 1970-01-01 returns
-  `BadOutOfRange`, because QuestDB cannot store it. Deletes there find nothing and return `BadNoEntryExists`. Pre-1970
-  conformance seeds are skipped for QuestDB.
-- The existence checks for Insert and Replace read committed data. If a live recorder sample at the *same*
-  timestamp is still in flight in the WAL, it can race the updater. Updates normally target past timestamps, so this
-  is accepted and documented.
+- **Ruling RC1 (T0 Q13):** an Insert, Replace or Update item timestamped before 1970-01-01 returns
+  `BadOutOfRange`, because QuestDB cannot store it (nothing is sent; a null or `MinValue` timestamp is still
+  `BadInvalidTimestamp`, and **as built** a pre-1970 item that is also NaN reports `BadOutOfRange`, not `BadInvalidArgument`,
+  because the pre-1970 filter runs first). DeleteAtTime there returns `BadNoEntryExists`; DeleteRaw finds nothing. A DeleteRaw
+  *window* may start before 1970. Pre-1970 conformance seeds are skipped for QuestDB.
+- **Concurrency (as built).** The updater serializes calls **per tag, in-process only** (64 striped async locks, held from the
+  existence read through the visibility wait), so two concurrent Insert/Replace/Delete batches on one tag cannot both act on a stale
+  read. It does **not** lock against the live writer or a second node. The existence checks read committed data, so a live recorder
+  sample at the *same* timestamp still in flight in the WAL can race the updater, and **two nodes writing the same new key
+  concurrently can produce last-write-wins** (QuestDB has no `UPDLOCK`; the Primary gate on the recorder makes it rare). Updates
+  normally target past timestamps, so this residual is accepted and documented.
 
 ### 2.4 Retention
 
@@ -242,10 +265,13 @@ T0-confirmed (Q5):
   formatted with `InvariantCulture`.
 - TTL is not allowed on the `PARTITION BY YEAR` `hist_tag` table (`TTL value must be an integer multiple of the
   partition size`).
+- **TTL is enforced only on write commits (as built, N3).** QuestDB looks for expired partitions when a write commits to the table,
+  so a quiet table never drops anything; old partitions linger until the next write.
 - **Reading the current TTL:** `SELECT ttlValue, ttlUnit FROM tables() WHERE table_name = $1`. QuestDB **normalises
   the unit**: 7 days reads `1 WEEK`, 14 days `2 WEEK`, 30 days `30 DAY`, none `0 HOUR`. The bootstrapper compares in
-  hours (`HOUR`=1, `DAY`=24, `WEEK`=168; any other unit counts as different) and issues an `ALTER` only on a
-  difference.
+  hours (`HOUR`=1, `DAY`=24, `WEEK`=168; any other unit counts as different, RC3) and issues an `ALTER` only on a
+  difference. A large `RetentionDays` that QuestDB normalises to MONTH/YEAR therefore re-`ALTER`s on every boot (harmless).
+  `AutoCreateSchema=false` touches no TTL.
 - `ALTER … SET TTL` is applied through the WAL, so `tables()` shows the old value for 25–100 ms. The bootstrapper does
   not re-read to verify.
 - Expiry is checked against the **wall clock**: the image default is `cairo.ttl.use.wall.clock=true`. A future-dated
@@ -261,7 +287,11 @@ T0-confirmed (Q5):
 Every query filters `NOT deleted`. Every value goes through `StoredSample`, so the quality clamp is the same as SQL
 Server's.
 
-- **Raw.** A range on `ts`, `ORDER BY ts [DESC]`, `LIMIT @top` (`maxValuesPerNode == 0` ⇒ unbounded), at most `top` samples, `ContinuationPoint: null`; the node manager pages by re-reading from the last timestamp (plan R8). The dedup key forbids same-instant ties. Bounds follow the existing data-source contract.
+- **Raw.** A range on `ts`, `ORDER BY ts [DESC]`, `LIMIT @top` (`maxValuesPerNode == 0` ⇒ unbounded), at most `top` samples, `ContinuationPoint: null`; the node manager pages by re-reading from the last timestamp (plan R8). The dedup key forbids same-instant ties. Bounds follow the existing data-source contract: forward `[start, end)`, reverse `(end, start]`
+  descending, and **(as built)** `start == end` reads the sample exactly at that (rounded) time. **(as built)** The data source reports
+  `TimestampResolutionTicks = 10`, and the node manager steps off the last drained timestamp by that amount (forward `T + 10`, reverse
+  `T − 10`): a 1-tick step is truncated back to `T`, so a one-value-per-page forward read would loop forever. The rule is *not* "trim
+  everything ≤ the last emitted", because the same paging serves the Gateway backend, where same-timestamp ties are legal.
   - **T0-confirmed form (review fix):** `SELECT ts, kind, num_value, int_value, str_value, status FROM {p}sample WHERE
     tag = $1 AND ts >= $2 AND ts < $3 AND NOT deleted ORDER BY ts [DESC] LIMIT $4`.
   - `$4` is a **bound** parameter, `NpgsqlDbType.Integer` (Int32) or `Bigint` (Int64); both work on 10.0.1, ASC and
@@ -283,15 +313,19 @@ Server's.
   ```
   `k` and `dir` are generated integer literals. Measured: 102 times in about 16–20 ms over 100k rows per tag, with no
   mismatches. `ASOF JOIN` was faster (1 ms), but it yields only the previous neighbour, so it was not chosen.
-  `AtTimeEvaluator` then decides the result.
-- **Events.** Filtered by source and `ts` range, ordered ascending (reversed windows are swapped, as built today),
-  and limited to `maxEvents`.
+  `AtTimeEvaluator` then decides the result. **(as built, M3)** Each time is evaluated at its *rounded* value but the result is stamped
+  with the time the client *requested* (UTC-normalised, not truncated), as on SQL Server, so answers match requests. Stored data is µs-only,
+  so a sub-µs request adjacent to a sample is an exact hit.
+- **Events.** Filtered by source and `ts` range `[start, end)`, ordered `(ts, event_id)` ascending (reversed windows are swapped, as built
+  today). **(as built)** With a bound, `maxEvents + 1` rows are fetched; the extra row is dropped and becomes the continuation point.
 - **Processed.** **One query per node** (T0-confirmed for every family; the S11 two-statement fallback is not needed).
   - Bucket index (T0-confirmed): `(cast(ts AS LONG) * 10 - $1) / $2`.
     - `cast(ts AS LONG)` is µs since 1970.
     - `$1` = the rounded window start in **ticks since the Unix epoch** (`start.Ticks − DateTime.UnixEpoch.Ticks`).
     - `$2` = the interval in ticks. Both are `NpgsqlDbType.Bigint`.
     - The result is exact because both sides are µs-aligned (R6), and it cannot overflow before year 9999.
+  - **(as built)** The bucket timestamp returned for a Processed bucket is the *rounded* window start plus `i × interval`, so with a
+    sub-µs request start it differs from SQL Server's label by the sub-µs remainder; values and membership are identical.
   - The query returns the full `BucketRow` statistics. Usable, good, bad and uncertain counts come from
     `sum(CASE …)` over the status column.
   - It does **not** use `SAMPLE BY`, whose alignment rules differ from ours. Computing the index ourselves keeps the
@@ -345,6 +379,11 @@ Server's.
 
 The Gateway keys (`Endpoint`, `ApiKey`, `UseTls`) are not required for QuestDb, the same as for SqlServer.
 
+**(as built) Pool size.** QuestDB's default limit is **64** PG-wire connections; Npgsql's default `Maximum Pool Size` is **100**, and the
+read, write, update and alarm paths share one pool per node. Operators should set `Maximum Pool Size` in the connection string below the
+server limit, per node (a redundant pair shares one QuestDB). The validator checks the prefix only when a consumer is enabled, but the
+connection helper also refuses a malformed prefix (`ArgumentException`) when the first seam is built.
+
 ## 5. Testing
 
 - **T1 refactor gate.** The SQL Server integration suite (118) and unit suite pass unchanged before and after the
@@ -364,7 +403,11 @@ The Gateway keys (`Endpoint`, `ApiKey`, `UseTls`) are not required for QuestDb,
   - concurrent bootstrap from two instances;
   - intra-batch microsecond collisions;
   - the `hist_tag` upsert;
-  - transient-failure behaviour, writing against a stopped port.
+  - transient-failure behaviour, writing against a stopped port;
+  - **(as built)** pre-1970 handling (writer drop, `BadOutOfRange`, read bounds), the `long.MinValue` read repair, Insert over a tombstone,
+    per-tag updater serialization, and a forward cap-1 paging regression against a real QuestDB.
+  - Conformance differences are named overrides: pre-1970 seeds are skipped on QuestDB, and AtTime timestamp assertions compare `Round(x)` to
+    the requested time (identity on SQL Server). The QuestDB fixture prunes idle pool connections after 1 s because of the 64-connection limit.
 - **Fixture.** `HISTORIAN_QUESTDB_TEST_CONNECTION`; when it is absent, the tests skip. Each test class uses a unique
   throwaway `TablePrefix` (`t_<guid>_`) and drops its tables on dispose.
 - **Host.** Registry and validator tests for `Backend=QuestDb`, beside the SqlServer ones.