chore: tighten error handling, document invariants, finish header migration

Bucket of small clarifications and the residual REUSE header migration.

- `error_mapping.rs`: replace the leak/debug-balance TODOs with a
  cross-link to the new "Logging and information disclosure" section
  in the README. The client-facing path is unchanged (still
  sanitised); operator logs keep the raw Trino message.
- `session.rs`: doc-comment on `CANCEL_REGISTRY` now lists the two
  drop sites that clean it up (`ConnectionCleanup` in main.rs and
  `ConnectionState::Drop` here) and explains why the invariant holds
  on idle TCP timeouts as well as normal close, error, and panic.
- `main.rs`: the over-cap connection drop is documented — the PG
  protocol *does* allow a graceful `ErrorResponse` (SQLSTATE 53300),
  but issuing it requires reading the StartupMessage first, which
  defeats the SYN-flood mitigation. We close at the TCP level and
  surface the cause via the `tracing::warn!`.
- `config.rs`: the `tls_cert` doc-comment used to say "operator-side
  discipline for now" and pointed at a publication-checklist item.
  `policy::validate` now enforces this at startup; comment updated.
- `startup.rs`: `rand::thread_rng().r#gen::<i32>()` -> `rand::random
  ::<i32>()`. The `r#gen` raw-identifier form was needed because
  `gen` became a keyword in Rust 2024; `random()` sidesteps it.
  Logging on credential check failure now mentions the broader
  cause (auth rejection / network error / unreachable Trino) rather
  than implying every failure is auth.
- `AGENTS.md`: added the `cargo llvm-cov --all-targets --html`
  invocation under Build & Test, behind a `cargo install`
  prerequisite note.
- All other touched files (cancel, handler, lib, policy, rewrite/*,
  catalog/{pg_type,stubs}, build.rs, scripts/*.sh, tests/integration_test.rs):
  inline SPDX header migration only. No content change.

Author: lfrancke

AGENTS.md

@@ -55,6 +55,10 @@ TRINO_HOST=... TRINO_PORT=... TRINO_SSL=true TRINO_TLS_NO_VERIFY=true \
 # With writable catalog (DDL tests):
 ... TRINO_WRITE_CATALOG=memory TRINO_WRITE_SCHEMA=default \
   cargo test
+
+# Coverage (requires `cargo install cargo-llvm-cov`):
+cargo llvm-cov --all-targets --html
+# HTML report at target/llvm-cov/html/index.html
 ```
 
 ## Quality Rules

build.rs

@@ -1,6 +1,5 @@
-// Copyright 2026 Stackable GmbH
-// Licensed under the Open Software License version 3.0 (OSL-3.0).
-// See LICENSE file in the project root for full license text.
+// SPDX-FileCopyrightText: 2026 Stackable GmbH
+// SPDX-License-Identifier: OSL-3.0
 fn main() {
     let timestamp = chrono::Utc::now()
         .format("%Y-%m-%d %H:%M:%S UTC")

scripts/build-static.sh

@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2026 Stackable GmbH
+# SPDX-License-Identifier: OSL-3.0
 # Build a statically-linked binary using musl.
 # The resulting binary runs on any Linux (no glibc dependency).
 #

scripts/build.sh

@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2026 Stackable GmbH
+# SPDX-License-Identifier: OSL-3.0
 # Build the gateway binary.
 # Produces a dynamically-linked binary at target/release/postgresql-trino-gateway.
 set -euo pipefail

scripts/connect.sh

@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2026 Stackable GmbH
+# SPDX-License-Identifier: OSL-3.0
 # Connect to the gateway with psql for testing.
 set -euo pipefail
 

scripts/start.sh

@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2026 Stackable GmbH
+# SPDX-License-Identifier: OSL-3.0
 # Start the PostgreSQL-Trino Gateway.
 # Configure via environment variables or edit the defaults below.
 set -euo pipefail

src/cancel.rs

@@ -1,6 +1,5 @@
-// Copyright 2026 Stackable GmbH
-// Licensed under the Open Software License version 3.0 (OSL-3.0).
-// See LICENSE file in the project root for full license text.
+// SPDX-FileCopyrightText: 2026 Stackable GmbH
+// SPDX-License-Identifier: OSL-3.0
 
 //! PostgreSQL `CancelRequest` handling.
 //!

src/catalog/pg_type.rs

@@ -1,6 +1,5 @@
-// Copyright 2026 Stackable GmbH
-// Licensed under the Open Software License version 3.0 (OSL-3.0).
-// See LICENSE file in the project root for full license text.
+// SPDX-FileCopyrightText: 2026 Stackable GmbH
+// SPDX-License-Identifier: OSL-3.0
 use std::sync::Arc;
 
 use pgwire::api::Type;

src/catalog/stubs.rs

@@ -1,6 +1,5 @@
-// Copyright 2026 Stackable GmbH
-// Licensed under the Open Software License version 3.0 (OSL-3.0).
-// See LICENSE file in the project root for full license text.
+// SPDX-FileCopyrightText: 2026 Stackable GmbH
+// SPDX-License-Identifier: OSL-3.0
 use std::sync::Arc;
 
 use pgwire::api::Type;

src/config.rs

@@ -1,6 +1,5 @@
-// Copyright 2026 Stackable GmbH
-// Licensed under the Open Software License version 3.0 (OSL-3.0).
-// See LICENSE file in the project root for full license text.
+// SPDX-FileCopyrightText: 2026 Stackable GmbH
+// SPDX-License-Identifier: OSL-3.0
 use std::path::PathBuf;
 
 use clap::Parser;
@@ -17,9 +16,8 @@ pub struct Config {
 
     /// PEM-encoded TLS certificate chain for the listening socket. When set,
     /// `--tls-key` is also required. Without these flags the gateway speaks
-    /// plaintext PG protocol; do not pair plaintext with `--auth` on a
-    /// non-loopback bind. (Operator-side discipline for now — automatic
-    /// refusal is tracked under publication-checklist item A11.)
+    /// plaintext PG protocol; the auth/TLS posture matrix in `policy.rs`
+    /// refuses plaintext + `--auth` on a non-loopback bind at startup.
     #[arg(long, requires = "tls_key")]
     pub tls_cert: Option<PathBuf>,