The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""Rows an earlier build or catalog stored whose values the current contract no longer lists.
Packaging re-checks every pending row against the current contract, so a value that left a closed
set after it was recorded (a catalog entry removed, a built-in tool moved to a plugin) is conformed
here instead of aborting the whole period's package (#133017).
"""
from __future__ import annotations
from typing import Any
from .shared_metrics_contract import (
_COUNTER_DIMENSION_VALUES,
_IDENTIFIER_FIELDS,
_LEGACY_METRIC_FIELDS,
_METRIC_FIELDS,
_metric_identifier,
)
def counter_dimensions_shape_is_known(metric_name: str, dimensions: dict[str, Any]) -> bool:
"""Whether the row's field set matches a current or legacy contract shape (values aside).
A row that fails this is structurally unknown — that is tamper evidence, not drift, and
packaging keeps failing closed on it (see test_package_builder_rejects_tampered_dimensions).
"""
fields = frozenset(dimensions)
return fields == _METRIC_FIELDS.get(metric_name) or fields in _LEGACY_METRIC_FIELDS.get(metric_name, ())
def conform_counter_dimensions(metric_name: str, dimensions: dict[str, Any]) -> dict[str, Any] | None:
"""Re-bucket out-of-contract enum values into the field's closed fallback, else ``None``.
Catalog-backed enums are repo data: a value that was a catalog entry when the row was
recorded (and passed record-time validation) can legitimately fall out of the catalog by
packaging time — the recording and packaging processes snapshot it independently (#133017).
Exporting the stale value would leak exactly the out-of-enum payload the closed enum exists
to prevent, so it is bucketed to ``custom``/``other``/``unknown`` (the first the field's enum
defines), mirroring what the record-side normalizers do for names that were never in the
catalog. Code constants drift too: a built-in tool moved to a plugin (Spotify, Home Assistant)
or a removed reason value leaves rows an earlier build stored.
Returns ``None`` when a value cannot be safely re-bucketed: fields whose enum defines no
fallback bucket, non-string values, or identifier fields that no longer round-trip through
``_metric_identifier`` (record-time validation already guarantees they did once).
"""
conformed = dict(dimensions)
identifiers = _IDENTIFIER_FIELDS.get(metric_name, {})
contract = _COUNTER_DIMENSION_VALUES[metric_name]
for field, value in conformed.items():
if not isinstance(value, str):
return None
if field in identifiers:
if value != _metric_identifier(value, max_length=identifiers[field]):
return None
continue
allowed = contract[field]
if value in allowed:
continue
fallback = next((bucket for bucket in ("custom", "other", "unknown") if bucket in allowed), None)
if fallback is None:
return None
conformed[field] = fallback
return conformed