fix: PR #4039 F2-1 follow-up — PG lowercase-then-quote across DDL/DML/detection

Closes the F2-1 reviewer comment "the SQLite / MySQL / PG V1 baselines deserve
the same scan" properly for PG, which F2 had deferred as a chain-wide limitation.
PG case-folds unquoted identifiers to lowercase at parse time, so reserved-keyword
table names (Order, User, Group, …) failed under the legacy unquoted DDL chain.
This commit makes the PG path quote-safe end-to-end while preserving backward
compatibility with existing folded tables.

Approach: lowercase the configured identifier first (matching PG's natural fold
of the legacy unquoted form), then double-quote at every emission site. A new
`PgIdentifier` helper centralizes this in the shared PG assembly.

DDL emitters (Wave A)
- PostgreSqlOutboxBuilder.GetDDL/GetExistsQuery and PostgreSqlInboxBuilder
  GetDDL/GetExistsQuery now emit `"schema"."table"` via PgIdentifier.
- PostgreSqlOutboxMigrationCatalog V1 historical DDL + V2..V7 ALTERs and
  PostgreSqlInboxMigrationCatalog V1 historical DDL apply the same convention.

Detection / validator / lock / history (Wave B)
- PostgreSqlBoxDetectionHelper user-table lookups (information_schema.tables,
  information_schema.columns, history-row params) PgIdentifier.Normalize the
  configured values so mixed-case defaults (e.g. "Outbox") match PG's stored
  folded form. This also closes a latent bug: pre-change detection passed the
  mixed-case configured name verbatim and would have missed `outbox` for any
  user on the framework default — only undetectable because tests use lowercase
  / GUID names exclusively.
- PostgreSqlBoxDetectionHelper.DoesHistoryExistAsync inlines the literal
  `__BrighterMigrationHistory` existence check so it bypasses the fold path —
  the system-table CREATE quotes the name and pg_class case-preserves it.
- PostgreSqlPayloadModeValidator normalizes its parameter values.
- PostgreSqlBoxMigrationRunner stores history rows under lowercase
  BoxTableName/SchemaName and hashes the advisory-lock key off the
  PG-normalized lock resource string.

Runtime DML (Wave C)
- RelationalDatabaseInbox.GenerateSqlText lifted from private to protected
  virtual to match the existing Outbox shape.
- PostgreSqlOutbox + PostgreSqlInbox override GenerateSqlText to lowercase-quote
  the configured table name before string.Format substitutes into the SQL
  templates — closes the runtime path for reserved-keyword names.

Tests + docs (Wave D)
- New end-to-end test pins the contract by configuring `OutBoxTableName = "Order"`
  (PG reserved keyword): asserts fresh install succeeds against the folded
  `order` table, history is keyed under lowercase, chain replay is a no-op,
  and PostgreSqlOutbox AddAsync/GetAsync round-trips a message through the
  reserved-keyword table.
- Full PG suite (182 tests) passes.
- docs/guides/box-provisioning-new-backend.md "Operational notes" section
  documents the PG fold-then-quote convention and the upgrade-safety story
  for existing deployments (history rows with mixed-case BoxTableName values
  become unreachable on read, but the ALTER chain is idempotent so the worst
  case is one no-op re-run).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: iancooper

docs/guides/box-provisioning-new-backend.md

@@ -267,6 +267,12 @@ The MySQL migration runner mutates its own connection string to set `AllowUserVa
 
 `BoxProvisioningOptions.MigrationLockTimeout` is honoured at millisecond resolution on MSSQL (`sp_getapplock`) and PG (`pg_try_advisory_lock` retry loop with a monotonic deadline), but MySQL's `GET_LOCK` takes an integer-second argument and SQLite's runner falls back to the same whole-second granularity. Sub-second timeouts on MySQL/SQLite are rounded **up** to 1 second — `TimeSpan.Zero` is **not** fail-fast on these backends. Cross-backend callers expecting fail-fast semantics should size their probe/deploy budgets accordingly.
 
+### PostgreSQL — identifiers are lowercased then quoted
+
+PostgreSQL case-folds unquoted identifiers to lowercase at parse time. Brighter's PG layer (DDL builders, migration catalogs, runtime DML, detection helpers, advisory-lock keys, and `__BrighterMigrationHistory` parameter values) all route configured table and schema names through `PgIdentifier.Normalize` / `PgIdentifier.Quote` — i.e. lowercased, then double-quoted at the emission site. This preserves continuity with historical Brighter PG deployments (where unquoted DDL produced lowercase physical tables regardless of the configured casing) **and** allows reserved-keyword table names (`Order`, `User`, `Group`, …) which the legacy unquoted form rejects as syntax errors. The internal `__BrighterMigrationHistory` table is created via quoted DDL and therefore remains case-preserved — its existence check bypasses the fold-normalization that user-table lookups go through.
+
+If you previously had a PG deployment with a mixed-case `OutBoxTableName` configured (e.g. the default `"Outbox"`), the upgrade is non-disruptive: the existing physical table is already named `outbox` in `pg_class`, and the new quoted form `"outbox"` resolves to the same table. History-table rows written before this normalization (with mixed-case `BoxTableName` values) become unreachable on read; the ALTER chain is idempotent (`ADD COLUMN IF NOT EXISTS`) so the worst case is a single re-run against an existing table — a no-op.
+
 ## Identifier safety
 
 Brighter's `Identifiers.AssertSafe` chokepoint validates table and schema names against `^[A-Za-z][A-Za-z0-9_]*$`. This is the **strictest backend's** rule (Spanner rejects `_`-prefixed names as reserved) applied framework-wide. If your new backend allows characters outside this set inside quoted/backticked identifiers, the chokepoint will still reject them — this is deliberate defence-in-depth. Do not loosen the regex; if your backend has a legitimate use case for an unusual identifier shape, rename the configuration value or document the constraint.

src/Paramore.Brighter.BoxProvisioning.PostgreSql/PostgreSqlBoxDetectionHelper.cs

@@ -29,6 +29,7 @@ THE SOFTWARE. */
 using Microsoft.Extensions.Logging.Abstractions;
 using Npgsql;
 using Paramore.Brighter.Logging;
+using Paramore.Brighter.PostgreSql;
 
 namespace Paramore.Brighter.BoxProvisioning.PostgreSql;
 
@@ -80,8 +81,14 @@ public async Task<bool> DoesTableExistAsync(
         command.CommandText = @"
 SELECT EXISTS(SELECT 1 FROM INFORMATION_SCHEMA.TABLES
 WHERE TABLE_SCHEMA = @SchemaName AND TABLE_NAME = @TableName)";
-        command.Parameters.AddWithValue("@SchemaName", schemaName ?? DefaultSchemaName);
-        command.Parameters.AddWithValue("@TableName", tableName);
+        // information_schema.tables stores PG-folded (lowercase) names. Normalize so a
+        // mixed-case configured value (e.g. default "Outbox") matches the stored "outbox".
+        // The internal __BrighterMigrationHistory system-table existence check does NOT
+        // route through this method — its CREATE DDL quotes the name and therefore
+        // case-preserves it in pg_class, so DoesHistoryExistAsync inlines a literal-name
+        // lookup that bypasses the fold normalization done here.
+        command.Parameters.AddWithValue("@SchemaName", PgIdentifier.Normalize(schemaName ?? DefaultSchemaName));
+        command.Parameters.AddWithValue("@TableName", PgIdentifier.Normalize(tableName));
 
         // Pattern-match rather than (bool)raw! so a driver returning null surfaces as a named
         // InvalidOperationException instead of a bare NullReferenceException — Npgsql has
@@ -103,18 +110,32 @@ public async Task<bool> DoesHistoryExistAsync(
         CancellationToken cancellationToken = default,
         NpgsqlTransaction? transaction = null)
     {
-        var historyTableExists = await DoesTableExistAsync(
-            connection, "__BrighterMigrationHistory", DefaultSchemaName, cancellationToken, transaction);
-        if (!historyTableExists)
-            return false;
+        // System-table existence: __BrighterMigrationHistory is created via quoted DDL
+        // (`CREATE TABLE IF NOT EXISTS "public"."__BrighterMigrationHistory"`), so its name
+        // is case-PRESERVED in pg_class. Routing through DoesTableExistAsync would lowercase
+        // the lookup to `'__brightermigrationhistory'` and miss. Inline the literal check.
+        using (var existsCmd = connection.CreateCommand())
+        {
+            if (transaction != null) existsCmd.Transaction = transaction;
+            existsCmd.CommandText = @"
+SELECT EXISTS(SELECT 1 FROM INFORMATION_SCHEMA.TABLES
+WHERE TABLE_SCHEMA = 'public' AND TABLE_NAME = '__BrighterMigrationHistory')";
+            var existsRaw = await existsCmd.ExecuteScalarAsync(cancellationToken);
+            var historyTableExists = existsRaw is bool b && b;
+            if (!historyTableExists)
+                return false;
+        }
 
         using var command = connection.CreateCommand();
         if (transaction != null) command.Transaction = transaction;
         command.CommandText = @"
 SELECT COUNT(1) FROM ""public"".""__BrighterMigrationHistory""
 WHERE ""BoxTableName"" = @BoxTableName AND ""SchemaName"" = @SchemaName";
-        command.Parameters.AddWithValue("@BoxTableName", tableName);
-        command.Parameters.AddWithValue("@SchemaName", schemaName ?? DefaultSchemaName);
+        // History rows are stored with PG-folded (lowercase) identifiers by the runner so
+        // that lookups remain consistent across mixed-case configured values; normalize
+        // here too. See PostgreSqlBoxMigrationRunner.InsertHistory.
+        command.Parameters.AddWithValue("@BoxTableName", PgIdentifier.Normalize(tableName));
+        command.Parameters.AddWithValue("@SchemaName", PgIdentifier.Normalize(schemaName ?? DefaultSchemaName));
 
         try
         {
@@ -160,8 +181,8 @@ public async Task<int> GetMaxVersionAsync(
         command.CommandText = @"
 SELECT COALESCE(MAX(""MigrationVersion""), 0) FROM ""public"".""__BrighterMigrationHistory""
 WHERE ""BoxTableName"" = @BoxTableName AND ""SchemaName"" = @SchemaName";
-        command.Parameters.AddWithValue("@BoxTableName", tableName);
-        command.Parameters.AddWithValue("@SchemaName", schemaName ?? DefaultSchemaName);
+        command.Parameters.AddWithValue("@BoxTableName", PgIdentifier.Normalize(tableName));
+        command.Parameters.AddWithValue("@SchemaName", PgIdentifier.Normalize(schemaName ?? DefaultSchemaName));
 
         var raw = await command.ExecuteScalarAsync(cancellationToken);
         return raw is int i
@@ -242,8 +263,8 @@ internal async Task<HashSet<string>> GetTableColumnsAsHashSetAsync(
         command.CommandText = @"
 SELECT column_name FROM information_schema.columns
 WHERE table_schema = @SchemaName AND table_name = @TableName";
-        command.Parameters.AddWithValue("@SchemaName", schemaName ?? DefaultSchemaName);
-        command.Parameters.AddWithValue("@TableName", tableName);
+        command.Parameters.AddWithValue("@SchemaName", PgIdentifier.Normalize(schemaName ?? DefaultSchemaName));
+        command.Parameters.AddWithValue("@TableName", PgIdentifier.Normalize(tableName));
 
         var columns = new HashSet<string>(StringComparer.Ordinal);
         using var reader = await command.ExecuteReaderAsync(cancellationToken);

src/Paramore.Brighter.BoxProvisioning.PostgreSql/PostgreSqlBoxMigrationRunner.cs

@@ -30,6 +30,7 @@ THE SOFTWARE. */
 using Npgsql;
 using Paramore.Brighter.Logging;
 using Paramore.Brighter.Observability;
+using Paramore.Brighter.PostgreSql;
 
 namespace Paramore.Brighter.BoxProvisioning.PostgreSql;
 
@@ -105,9 +106,12 @@ protected override Task<IAmAProvisioningUnitOfWork<NpgsqlTransaction>> CreateUni
     // Include the schema in the lock key so two same-named tables in different schemas
     // (e.g. public.Outbox and billing.Outbox) acquire distinct advisory locks. Without
     // the schema qualifier they would share a lock and serialize unnecessarily — matches
-    // the MSSQL runner's lockResource shape.
+    // the MSSQL runner's lockResource shape. Lowercase the identifiers so callers that
+    // configure the same physical table with different casings (e.g. "Outbox" vs
+    // "outbox" — both folded to `outbox` by PG) hash to the same lock key.
     protected override string LockResourceFor(string? schemaName, string tableName)
-        => $"BrighterMigration_{schemaName ?? HISTORY_TABLE_SCHEMA}.{tableName}";
+        => $"BrighterMigration_{PgIdentifier.Normalize(schemaName ?? HISTORY_TABLE_SCHEMA)}.{PgIdentifier.Normalize(tableName)}";
+
 
     protected override async Task EnsureHistoryTableAsync(
         NpgsqlConnection connection, NpgsqlTransaction? transaction, string? schemaName,
@@ -290,8 +294,14 @@ private static async Task InsertHistoryRowAsync(
 INSERT INTO ""{HISTORY_TABLE_SCHEMA}"".""{MIGRATION_HISTORY_TABLE}"" (""MigrationVersion"", ""SchemaName"", ""BoxTableName"", ""Description"")
 VALUES (@Version, @SchemaName, @BoxTableName, @Description)";
         command.Parameters.AddWithValue("@Version", version);
-        command.Parameters.AddWithValue("@SchemaName", schemaName);
-        command.Parameters.AddWithValue("@BoxTableName", tableName);
+        // Store PG-folded (lowercase) identifiers so history rows match the case of the
+        // physical table PG actually created — and so lookups via the detection helper
+        // (which normalizes the same way) hit the same row regardless of the configured
+        // casing. Existing rows written before this normalization remain in the table but
+        // become unreachable on read; the ALTER chain is idempotent (`ADD COLUMN IF NOT
+        // EXISTS`) so a re-run against an existing table is a no-op.
+        command.Parameters.AddWithValue("@SchemaName", PgIdentifier.Normalize(schemaName));
+        command.Parameters.AddWithValue("@BoxTableName", PgIdentifier.Normalize(tableName));
         command.Parameters.AddWithValue("@Description", description);
 
         await command.ExecuteNonQueryAsync(cancellationToken);

src/Paramore.Brighter.BoxProvisioning.PostgreSql/PostgreSqlInboxMigrationCatalog.cs

@@ -24,6 +24,7 @@ THE SOFTWARE. */
 using System;
 using System.Collections.Generic;
 using Paramore.Brighter.Inbox.Postgres;
+using Paramore.Brighter.PostgreSql;
 
 namespace Paramore.Brighter.BoxProvisioning.PostgreSql;
 
@@ -55,12 +56,12 @@ public class PostgreSqlInboxMigrationCatalog : IAmABoxMigrationCatalog
     // Literal historical PostgreSQL inbox DDL extracted from commit 1cdc04b60 (Nov 2023, PR
     // #2560). First-shipped state already carried ContextKey with a composite PRIMARY KEY on
     // (CommandId, ContextKey) — see the V1-only/born-past-V1 note in the class remarks.
-    // {0} = table name (validated).
-    // Intentionally NOT double-quoted — PG identifiers are case-folded when unquoted and the
-    // PG inbox is V1-only (no V2+ chain). Quoting V1 here would change runtime semantics for
-    // existing deployments (case-folded `outbox`-style lookups would miss a now case-sensitive
-    // table). Reserved-keyword identifiers (e.g. "Order") are a chain-wide PG limitation, not
-    // a V1-specific gap. Per PR #4039 reviewer item F2-1.
+    // {0} = quoted, lowercased table identifier (via PgIdentifier).
+    // Lowercase-then-quote: PG case-folds unquoted identifiers to lowercase at parse time, so
+    // the legacy unquoted form created e.g. `inbox` from a configured `"Inbox"`. Quoting the
+    // already-lowercased form ("inbox") resolves to the same physical table as the legacy
+    // unquoted form, AND lets reserved-keyword names (User, Order, …) parse cleanly. All
+    // PG catalogs and builders share this fold-then-quote convention via PgIdentifier.
     private const string V1HistoricalDdl =
         """
         CREATE TABLE {0}
@@ -114,7 +115,7 @@ public IReadOnlyList<IAmABoxMigration> All(IAmARelationalDatabaseConfiguration c
             new BoxMigration(
                 Version: 1,
                 Description: "Create inbox table",
-                UpScript: string.Format(V1HistoricalDdl, configuration.InBoxTableName),
+                UpScript: string.Format(V1HistoricalDdl, PgIdentifier.Quote(configuration.InBoxTableName)),
                 LogicalColumns: new HashSet<string>(StringComparer.Ordinal)
                 {
                     "commandid", "commandtype", "commandbody", "timestamp", "contextkey"

src/Paramore.Brighter.BoxProvisioning.PostgreSql/PostgreSqlOutboxMigrationCatalog.cs

@@ -25,6 +25,7 @@ THE SOFTWARE. */
 using System.Collections.Generic;
 using System.Linq;
 using Paramore.Brighter.Outbox.PostgreSql;
+using Paramore.Brighter.PostgreSql;
 
 namespace Paramore.Brighter.BoxProvisioning.PostgreSql;
 
@@ -74,13 +75,14 @@ public class PostgreSqlOutboxMigrationCatalog : IAmABoxMigrationCatalog
 
     // Literal historical PostgreSQL outbox DDL extracted from commit 3c30343fa (July 2019).
     // First-shipped state already carried Dispatched — see the born-past-V1 note in the
-    // class remarks. {0} = table name (validated).
-    // Intentionally NOT double-quoted — V2..V7 ALTERs in this catalog also use unquoted
-    // identifiers and rely on PG's identifier case-folding. Adding "{0}" to V1 would create
-    // a case-sensitive table that the unquoted V2..V7 ALTERs could not reach, so V1 stays
-    // symmetric with the rest of the chain. Reserved-keyword identifiers (e.g. "Order") are
-    // a chain-wide limitation on PG, not a V1-specific gap — discussed under PR #4039
-    // reviewer item F2-1 and tracked separately if it ever becomes a real constraint.
+    // class remarks. {0} = quoted, lowercased table identifier (via PgIdentifier).
+    // Lowercase-then-quote: PG case-folds unquoted identifiers to lowercase at parse time,
+    // so historical tables created via the unquoted builder DDL live as e.g. `outbox` in
+    // pg_class regardless of the configured `OutBoxTableName = "Outbox"`. Quoting the
+    // already-lowercased form ("outbox") resolves to the same physical table as the legacy
+    // unquoted form would have, AND unlocks reserved-keyword names (Order, User, Group, …)
+    // that the unquoted V2..V7 ALTERs would otherwise reject as syntax errors. All catalogs
+    // and builders in this chain apply the same fold-then-quote rule via PgIdentifier.
     private const string V1HistoricalDdl =
         """
         CREATE TABLE {0}
@@ -137,7 +139,7 @@ public IReadOnlyList<IAmABoxMigration> All(IAmARelationalDatabaseConfiguration c
             new BoxMigration(
                 Version: 1,
                 Description: "Create outbox table",
-                UpScript: string.Format(V1HistoricalDdl, table),
+                UpScript: string.Format(V1HistoricalDdl, PgIdentifier.Quote(table)),
                 LogicalColumns: Cumulative(1)),
 
             new BoxMigration(
@@ -215,5 +217,9 @@ private static string AddColumns(string schema, string table, params (string Col
         string.Join(Environment.NewLine, columns.Select(c => AddColumn(schema, table, c.Column, c.Type)));
 
     private static string AddColumn(string schema, string table, string column, string type) =>
-        $"ALTER TABLE {schema}.{table} ADD COLUMN IF NOT EXISTS {column} {type} NULL;";
+        // schema/table are lowercase-then-quoted via PgIdentifier so the ALTER targets the
+        // same physical table that V1's CREATE produced — and so reserved-keyword names
+        // (Order, User, Group, …) parse cleanly. Column names are sourced from the catalog
+        // and are already ADR 0057 §1 lowercase, so they are emitted bare.
+        $"ALTER TABLE {PgIdentifier.QuoteQualified(schema, table)} ADD COLUMN IF NOT EXISTS {column} {type} NULL;";
 }

src/Paramore.Brighter.BoxProvisioning.PostgreSql/PostgreSqlPayloadModeValidator.cs

@@ -24,6 +24,7 @@ THE SOFTWARE. */
 using System.Threading;
 using System.Threading.Tasks;
 using Npgsql;
+using Paramore.Brighter.PostgreSql;
 
 namespace Paramore.Brighter.BoxProvisioning.PostgreSql;
 
@@ -60,9 +61,11 @@ public async Task ValidateAsync(
         command.CommandText = @"
 SELECT data_type FROM information_schema.columns
 WHERE table_schema = @SchemaName AND table_name = @TableName AND column_name = @ColumnName";
-        command.Parameters.AddWithValue("@SchemaName", resolvedSchema);
-        command.Parameters.AddWithValue("@TableName", tableName);
-        command.Parameters.AddWithValue("@ColumnName", columnName);
+        // information_schema.columns stores PG-folded (lowercase) identifiers. Normalize
+        // configured values so mixed-case defaults match the stored folded form.
+        command.Parameters.AddWithValue("@SchemaName", PgIdentifier.Normalize(resolvedSchema));
+        command.Parameters.AddWithValue("@TableName", PgIdentifier.Normalize(tableName));
+        command.Parameters.AddWithValue("@ColumnName", PgIdentifier.Normalize(columnName));
 
         var dataType = (string?)await command.ExecuteScalarAsync(cancellationToken);
         if (dataType == null) return;

src/Paramore.Brighter.Inbox.Postgres/PostgreSqlInbox.cs

@@ -25,6 +25,7 @@ THE SOFTWARE. */
 
 using System;
 using System.Data;
+using System.Linq;
 using Npgsql;
 using NpgsqlTypes;
 using Paramore.Brighter.Logging;
@@ -63,4 +64,15 @@ protected override IDbDataParameter CreateJsonSqlParameter(string parameterName,
     {
         return new NpgsqlParameter { ParameterName = parameterName, NpgsqlDbType = DatabaseConfiguration.BinaryMessagePayload ? NpgsqlDbType.Jsonb : NpgsqlDbType.Json,Value = value ?? DBNull.Value };
     }
+
+    /// <summary>
+    /// Lowercase-then-quote the configured inbox table name so reserved-keyword names
+    /// (Order, User, Group, …) parse cleanly and mixed-case configured values resolve to
+    /// the same physical table as PG's natural case-fold of the legacy unquoted form would
+    /// have produced.
+    /// </summary>
+    protected override string GenerateSqlText(string sqlFormat, params string[] orderedParams)
+        => string.Format(
+            sqlFormat,
+            orderedParams.Prepend(PgIdentifier.Quote(DatabaseConfiguration.InBoxTableName)).ToArray());
 }