feat: record each call's tenant and caller-defined dimensions

Both telemetry backends gain tenant_id and meta at the end of the
column list, and TelemetryEmitter fills them from the request. The two
halves ship together because the emitter is the only caller of
record_llm_call: adding the columns without filling them leaves every
row short of two keys, and the backends read those keys outside their
try block, so the KeyError degrades to a warning and the whole table
stops filling.

The columns are appended, never inserted. An old table can only gain
columns through ALTER, which puts them last; a new table built from the
DDL would put them wherever the DDL says. Anywhere but the end and the
two paths produce different physical column orders, while the INSERT
uses positional placeholders.

The two backends spell the default differently for different reasons.
SQLite refuses a NOT NULL column without a non-NULL constant default
outright, so the default is what makes the backfill legal at all. On
Postgres a non-volatile constant default is what keeps the ALTER from
rewriting the table, and NOT NULL DEFAULT '' is what keeps old rows out
of the black hole a NULL tenant_id falls into under an RLS policy.

Normalisation happens in the emitter, not the recorder, matching how
canonical_sampling_json already settles the sampling column: None
becomes the empty string, an empty mapping becomes the literal '{}'.
Keys are sorted so one set of dimensions serialises identically on
every row, and allow_nan=False is a second gate behind the entry
validation -- json.dumps would otherwise write a bare NaN, which JSONB
rejects, and the failed insert would be swallowed as a warning.

All three emit entry points read the request. Cache hits read it too,
rather than the replayed response: the dimensions answer who made this
call, not who made the one whose result is being replayed.

src/polygateway/middleware/telemetry.py

@@ -26,13 +26,30 @@ from polygateway.middleware.cache import digest_messages
 from polygateway.types import canonical_sampling_json, merge_sampling
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
+    from collections.abc import Callable, Mapping
+    from typing import Any
 
     from polygateway.ports import CallNext, TelemetryRecorder
     from polygateway.pricing import PricingTable
     from polygateway.types import ChatRequest, LLMResponse, SourceConfig
 
 
+def _canonical_meta_json(meta: Mapping[str, Any]) -> str:
+    """把调用方自定义维度定型为 JSON 文本(issue #11);空 dict 落字面量 `'{}'`。
+
+    `sort_keys=True` 让同一份维度在任意两行里字节一致,可直接等值比对与去重;
+    `ensure_ascii=False` 保留中文原文,避免落库成 `\\uXXXX` 串而无法肉眼审计。
+
+    `allow_nan=False` 是**第二道闸**(主防线是 `types.validate_caller_dimensions`
+    在公共入口的校验): `json.dumps` 默认把 `nan` 写成裸 `NaN` 字面量,那不是合法
+    JSON,PG 的 JSONB 会拒收;而写入失败会被 `_record` 的降级 try 吞成 warning,
+    等于把调用方的输入错误转化成静默丢遥测。宁可在这里显式抛。
+    """
+    if not meta:
+        return "{}"
+    return json.dumps(dict(meta), sort_keys=True, ensure_ascii=False, allow_nan=False)
+
+
 @dataclass(frozen=True)
 class _AttemptUsage:
     """一次尝试的用量视图;默认值即"失败尝试"档(无用量可言,记 0 并标 unavailable)。
@@ -72,7 +89,7 @@ class _AttemptUsage:
 
 
 class TelemetryEmitter:
-    """从请求与结果组装 21 字段并写入 recorder;一切写失败降级 warning。"""
+    """从请求与结果组装 24 字段并写入 recorder;一切写失败降级 warning。"""
 
     def __init__(self, recorder: TelemetryRecorder, *, pricing: PricingTable | None = None) -> None:
         self._recorder = recorder
@@ -111,6 +128,8 @@ class TelemetryEmitter:
             reasoning_tokens=usage.reasoning_tokens,
             # 唯一有"生效源"的入口,故是唯一能并上 extra_body 的(设计决策 D)
             sampling=canonical_sampling_json(merge_sampling(source.extra_body, request.sampling)),
+            tenant_id=request.tenant_id,
+            meta=request.meta,
         )
 
     async def emit_cache_hit(self, *, request: ChatRequest, response: LLMResponse) -> None:
@@ -139,6 +158,11 @@ class TelemetryEmitter:
             # 由最外层 TelemetryMW 调用,手上没有 source。缓存命中行无损:
             # sampling 已进缓存 key,能命中即意味调用级参数与历史那次逐字相同
             sampling=canonical_sampling_json(request.sampling),
+            # 与上面的 model/prompt_tokens 相反,维度读 request 而非 response:
+            # 维度回答的是"本次调用由谁发起",不是历史那次。读历史会把本次调用
+            # 记到上一个租户头上,两边的账同时错且无任何报错(issue #11 设计 §4.3)
+            tenant_id=request.tenant_id,
+            meta=request.meta,
         )
 
     async def emit_terminal_failure(
@@ -166,6 +190,9 @@ class TelemetryEmitter:
             reasoning_tokens=None,
             # 无具体源,与 model/provider/source_name 置空同一先例(设计决策 D)
             sampling=canonical_sampling_json(request.sampling),
+            # 源不可知,但租户归属是已知的——终态失败行恰是审计最需要的
+            tenant_id=request.tenant_id,
+            meta=request.meta,
         )
 
     async def _record(
@@ -190,6 +217,9 @@ class TelemetryEmitter:
         model_reported: str | None,
         sampling: str | None,
         reasoning_tokens: int | None,
+        # issue #11: 未归一化的调用方维度,归一化在本方法内收口(recorder 只落库)
+        tenant_id: str | None,
+        meta: Mapping[str, Any],
     ) -> None:
         try:
             # 成本换算(M2 §6): 成功行按单价换算;缓存命中 0.0(未产生新调用);
@@ -231,6 +261,10 @@ class TelemetryEmitter:
                 model_reported=model_reported,
                 sampling=sampling,
                 reasoning_tokens=reasoning_tokens,
+                # 空串是哨兵而非 NULL: NULL 的 tenant_id 在 PG 的 RLS policy 下
+                # 对所有人永久不可见,空串则可用一条 SQL 审计出未归属的行
+                tenant_id=tenant_id or "",
+                meta=_canonical_meta_json(meta),
             )
         except asyncio.CancelledError:
             raise

src/polygateway/ports.py

@@ -245,10 +245,15 @@ class StructuredOutputStrategy(Protocol):
 
 @runtime_checkable
 class TelemetryRecorder(Protocol):
-    """遥测后端;22 字段冻结(M1 设计 §4.4 + issue #3/#4),唯一调用点是 TelemetryEmitter。
+    """遥测后端;24 字段冻结(M1 设计 §4.4 + issue #3/#4/#11),唯一调用点是 TelemetryEmitter。
 
     新增参数不设默认值: 库外无第三方实现者(三项目迁移时删除了各自的同名
     Protocol),完整签名的成本为零,而少写一列会被 emitter 的降级吞成 warning。
+
+    `tenant_id` 与 `meta` 到达 recorder 时**已由 emitter 归一化**——`tenant_id`
+    的 `None` 已转空串,`meta` 已序列化为 JSON 字符串(空 dict 为 `'{}'`)。
+    recorder 只负责落库,不做任何语义判断,与 `sampling` 列由
+    `canonical_sampling_json()` 在 emitter 侧定型是同一先例。
     """
 
     async def record_llm_call(
@@ -276,4 +281,6 @@ class TelemetryRecorder(Protocol):
         model_reported: str | None,
         sampling: str | None,
         reasoning_tokens: int | None,
+        tenant_id: str,
+        meta: str,
     ) -> None: ...

src/polygateway/telemetry/postgres.py

@@ -48,7 +48,9 @@ CREATE TABLE IF NOT EXISTS llm_calls (
     cached_prompt_tokens INTEGER,
     model_reported       TEXT,
     sampling             TEXT,
-    reasoning_tokens     INTEGER
+    reasoning_tokens     INTEGER,
+    tenant_id            TEXT NOT NULL DEFAULT '',
+    meta                 JSONB NOT NULL DEFAULT '{}'::jsonb
 );
 """
 
@@ -58,6 +60,15 @@ _BACKFILL = (
     ("model_reported", "ALTER TABLE llm_calls ADD COLUMN model_reported TEXT"),
     ("sampling", "ALTER TABLE llm_calls ADD COLUMN sampling TEXT"),
     ("reasoning_tokens", "ALTER TABLE llm_calls ADD COLUMN reasoning_tokens INTEGER"),
+    # 两个默认值都是非易失常量,PG 11+ 只改 catalog 不重写全表,故大表补列亦是秒级
+    (
+        "tenant_id",
+        "ALTER TABLE llm_calls ADD COLUMN tenant_id TEXT NOT NULL DEFAULT ''",
+    ),
+    (
+        "meta",
+        "ALTER TABLE llm_calls ADD COLUMN meta JSONB NOT NULL DEFAULT '{}'::jsonb",
+    ),
 )
 
 # 探测表是否存在;不需要任何权限,且与 INSERT 走同一套 search_path 解析
@@ -92,6 +103,8 @@ _COLUMNS = (
     "model_reported",
     "sampling",
     "reasoning_tokens",
+    "tenant_id",
+    "meta",
 )
 
 _INSERT = (

src/polygateway/telemetry/sqlite.py

@@ -46,7 +46,9 @@ CREATE TABLE IF NOT EXISTS llm_calls (
     cached_prompt_tokens INTEGER,
     model_reported       TEXT,
     sampling             TEXT,
-    reasoning_tokens     INTEGER
+    reasoning_tokens     INTEGER,
+    tenant_id            TEXT    NOT NULL DEFAULT '',
+    meta                 TEXT    NOT NULL DEFAULT '{}'
 );
 """
 
@@ -57,6 +59,10 @@ _BACKFILL_COLUMNS = (
     ("model_reported", "TEXT"),
     ("sampling", "TEXT"),
     ("reasoning_tokens", "INTEGER"),
+    # NOT NULL 补列必须带非 NULL 常量默认值,否则 SQLite 直接拒绝该 ALTER
+    # ("Cannot add a NOT NULL column with default value NULL"),补列全盘失败。
+    ("tenant_id", "TEXT NOT NULL DEFAULT ''"),
+    ("meta", "TEXT NOT NULL DEFAULT '{}'"),
 )
 
 _COLUMNS = (
@@ -82,6 +88,8 @@ _COLUMNS = (
     "model_reported",
     "sampling",
     "reasoning_tokens",
+    "tenant_id",
+    "meta",
 )
 
 _INSERT = (
@@ -137,7 +145,7 @@ class SQLiteRecorder:
                     logger.warning("SQLite 遥测补列失败(写入将逐行降级): {}", exc)
 
     async def record_llm_call(self, **fields: object) -> None:
-        """写一行遥测;字段集合即 21 字段冻结签名(ports.TelemetryRecorder)。"""
+        """写一行遥测;字段集合即 24 字段冻结签名(ports.TelemetryRecorder)。"""
         if self._conn is None:
             return
         row = tuple(fields[col] for col in _COLUMNS)