feat: make the telemetry pool declare what it costs

The pool was the only external resource in the library that pre-allocated:
asyncpg's default min_size=10 turned pool creation into an all-or-nothing
action, so on a shared instance running low on connection budget the first
thing to fall over was the one component that must not fail silently
(4 clients x 10 = 40 idle connections just to write telemetry).

min_size=0 means "do not pre-connect" - asyncpg only builds holders - so
pool creation becomes free and never touches the database; connection
failures then land on acquire, the path that already drops one row and lets
the pool recover. max_size and the write budget become the library's
explicit statement about its own footprint, configurable through two new
keys whose defaults live in config alone (the recorder parameters are
required keyword-only, same discipline as auto_migrate).

The whole write - prepare, acquire, execute - now runs inside one
asyncio.timeout: acquire used to have no timeout at all, so a full pool
would hang forever on the caller's path. Release is explicit rather than
`async with`, because asyncpg shields release and reuses the acquire
timeout, which would let a single telemetry write consume twice the budget.

tests/unit/test_config.py

@@ -425,6 +425,73 @@ class TestTelemetryTextCap:
             GatewaySettings.from_env("LLM", env=_env(PGW_TELEMETRY_TEXT_CAP="2k"))
 
 
+class TestTelemetryPoolKeys:
+    """`PGW_TELEMETRY_PG_POOL_MAX` / `PGW_TELEMETRY_PG_WRITE_TIMEOUT_S`(issue #15)。
+
+    两键都带 `PG` 前缀,与 `PGW_TELEMETRY_PG_DSN` 一致: SQLite 侧没有池、也没有
+    等价的写入预算旋钮,这个不对称是已知且有理由的。缺省值(4 / 5.0)只写在
+    config 一处——recorder 的两个同名参数是必填 keyword-only,不许各带一份缺省。
+    """
+
+    def _pg_env(self, **overrides):
+        return _env(
+            PGW_TELEMETRY_BACKEND="postgres",
+            PGW_TELEMETRY_PG_DSN="postgresql://u:p@h:5432/polygateway",
+            **overrides,
+        )
+
+    def test_unset_keys_fall_back_to_the_documented_defaults(self):
+        s = GatewaySettings.from_env("LLM", env=self._pg_env())
+        assert s.telemetry_pg_pool_max == 4
+        assert s.telemetry_pg_write_timeout_s == 5.0
+
+    def test_values_parsed_from_env(self):
+        s = GatewaySettings.from_env(
+            "LLM",
+            env=self._pg_env(PGW_TELEMETRY_PG_POOL_MAX="8", PGW_TELEMETRY_PG_WRITE_TIMEOUT_S="1.5"),
+        )
+        assert s.telemetry_pg_pool_max == 8
+        assert s.telemetry_pg_write_timeout_s == 1.5
+
+    @pytest.mark.parametrize("raw", ["0", "-1"])
+    def test_non_positive_pool_max_rejected_naming_the_env_key(self, raw):
+        """池上限 0 = 永远拿不到连接(遥测全灭),负数无意义。"""
+        with pytest.raises(ValueError, match="PGW_TELEMETRY_PG_POOL_MAX"):
+            GatewaySettings.from_env("LLM", env=self._pg_env(PGW_TELEMETRY_PG_POOL_MAX=raw))
+
+    @pytest.mark.parametrize("raw", ["0", "-1"])
+    def test_non_positive_write_timeout_rejected_naming_the_env_key(self, raw):
+        """预算 0 = 每一行都当场超预算;不设预算不是这个键的写法。"""
+        with pytest.raises(ValueError, match="PGW_TELEMETRY_PG_WRITE_TIMEOUT_S"):
+            GatewaySettings.from_env("LLM", env=self._pg_env(PGW_TELEMETRY_PG_WRITE_TIMEOUT_S=raw))
+
+    def test_non_numeric_rejected_naming_the_env_key(self):
+        with pytest.raises(ValueError, match="PGW_TELEMETRY_PG_POOL_MAX"):
+            GatewaySettings.from_env("LLM", env=self._pg_env(PGW_TELEMETRY_PG_POOL_MAX="many"))
+
+    @pytest.mark.parametrize(
+        ("field", "value"),
+        [("telemetry_pg_pool_max", 0), ("telemetry_pg_write_timeout_s", 0.0)],
+    )
+    def test_direct_construction_and_replace_are_validated_too(self, field, value):
+        """env 路只覆盖 from_env;直接构造与 replace 是同等官方的装配路(与 text_cap 同款)。"""
+        base = GatewaySettings.from_env("LLM", env=_env())
+        with pytest.raises(ValueError, match=field):
+            dataclasses.replace(base, **{field: value})
+
+    def test_values_reach_the_recorder(self):
+        """配置到 recorder 之间不得断链——两个键唯一的作用就是抵达那里。"""
+        from polygateway.client import _build_telemetry
+
+        settings = GatewaySettings.from_env(
+            "LLM",
+            env=self._pg_env(PGW_TELEMETRY_PG_POOL_MAX="7", PGW_TELEMETRY_PG_WRITE_TIMEOUT_S="2.5"),
+        )
+        recorder = _build_telemetry(settings)
+        assert recorder._pool_max == 7
+        assert recorder._write_timeout_s == 2.5
+
+
 class TestOcrSettings:
     """M3 OcrSettings(设计 §3.4): 复用 GatewaySettings,无 OCR 专用键。"""