xakki-log-python 0.4.0__py3-none-any.whl

log_python/context.py

@@ -0,0 +1,575 @@
+"""Context field type-coercion table.
+
+Python port of `LogManager::$contextTypeRules` / `LogManager::contextTypeCorrector()`
+and friends (reference `src/LogManager.php`, spec `docs/ContextFieldNaming.md`). This is
+the field-type stability contract: OpenSearch gives a field its type from the first
+document it appears in and has no `ignore_malformed` set, so if the same field name
+ever emits two different JSON types across services, the SECOND document is silently
+dropped whole — not just the offending field. The rule table below is what prevents
+that: a context key's NAME decides its JSON type, deterministically, everywhere.
+
+By default a field is a string. The key is split into `_`-delimited segments; the
+LAST segment usually decides the type, matched as a whole segment, never a substring
+(`report` does not see `port`, `datetime` does not see `time`). Resolution order,
+first match wins (§1 of the spec):
+
+1. ``suffix``   — escape hatch: last segment ``int``/``float``/``bool``. Beats
+                  everything else, including ``reserved``.
+2. ``reserved`` — whole key; fields this library writes itself.
+3. ``exact``    — whole key, lowercased; project override level.
+4. ``word``     — last segment.
+5. ``prefix``   — first segment, only for keys with 2+ segments.
+6. no rule      — the default: string.
+
+This module has zero third-party dependencies (stdlib only), per the project's
+zero-runtime-dependency contract for the core.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import json
+import math
+import re
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from types import MappingProxyType
+from typing import Final
+
+from log_python.config import PylogConfig
+from log_python.const import LOGGER_MCTIME, LOGGER_MEMORY, LOGGER_MEMORY_PEAK, LOGGER_SKIP_TRACE
+
+_BOUND_CONTEXT: Final[contextvars.ContextVar[Mapping[str, object]]] = contextvars.ContextVar("pylog_bound_context", default=MappingProxyType({}))
+
+
+def get_bound_context() -> dict[str, object]:
+    """Return a copy of context bound to the current thread/async task."""
+    return dict(_BOUND_CONTEXT.get())
+
+
+def bind(**values: object) -> None:
+    """Merge values into the current logging context."""
+    current = get_bound_context()
+    current.update(values)
+    _BOUND_CONTEXT.set(MappingProxyType(current))
+
+
+def clear() -> None:
+    """Clear all context bound to the current thread/async task."""
+    _BOUND_CONTEXT.set(MappingProxyType({}))
+
+
+@contextmanager
+def bound_context(**values: object) -> Iterator[None]:
+    """Temporarily merge values into the bound context."""
+    token = _BOUND_CONTEXT.set(MappingProxyType({**_BOUND_CONTEXT.get(), **values}))
+    try:
+        yield
+    finally:
+        _BOUND_CONTEXT.reset(token)
+
+
+def remote_ip(value: str | None) -> None:
+    """Bind a non-empty remote address from framework middleware."""
+    if value:
+        bind(remote_ip=value)
+
+
+# ---------------------------------------------------------------------------
+# Type constants — same five values as LogManager::CONTEXT_TYPE_*.
+# ---------------------------------------------------------------------------
+
+CONTEXT_TYPE_INT: Final[str] = "int"
+CONTEXT_TYPE_FLOAT: Final[str] = "float"
+CONTEXT_TYPE_BOOL: Final[str] = "bool"
+CONTEXT_TYPE_STRING: Final[str] = "string"
+# "the corrector's caller (log()) consumes this itself, do not touch" — LogManager.php.
+CONTEXT_TYPE_SKIP: Final[str] = "skip"
+
+_VALID_TYPES: Final[frozenset[str]] = frozenset({CONTEXT_TYPE_INT, CONTEXT_TYPE_FLOAT, CONTEXT_TYPE_BOOL, CONTEXT_TYPE_STRING, CONTEXT_TYPE_SKIP})
+
+# Lucene refuses to index a term longer than 32766 bytes; cap below that. BYTE count
+# (UTF-8), not character count — matches PHP's `strlen()`/`mb_strcut()` pairing.
+CONTEXT_MAX_STRING_BYTES: Final[int] = 32000
+
+# Depth bound for the JSON-encoding of a nested value under a scalar rule (guards
+# recursion / huge blobs). Reference: LogManager::CONTEXT_JSON_MAX_DEPTH.
+_CONTEXT_JSON_MAX_DEPTH: Final[int] = 16
+
+# Lowercased strings meaning boolean false. Legacy data really does ship 'F', and a
+# blind `bool('F')` is truthy in both languages, so this is an explicit table, not a
+# cast. Reference: LogManager::CONTEXT_FALSE_VALUES.
+CONTEXT_FALSE_VALUES: Final[frozenset[str]] = frozenset({"", "0", "f", "false", "n", "no", "off"})
+
+# PHP_INT_MAX (2**63 - 1, the 64-bit signed integer boundary). Python `int` has no such
+# limit, but the coercion decision (int vs. string fallback) must land on the SAME side
+# of the line as the PHP fleet for a given value, or the same field name emits two JSON
+# types across services — the exact failure this whole module exists to prevent. So this
+# threshold is carried over verbatim rather than dropped as "PHP-only cruft". The PHP
+# source also compares against `(float) PHP_INT_MAX`, which rounds up to 2**63 in IEEE-754
+# double precision; `float(_PHP_INT_MAX)` below reproduces the identical rounding, since
+# Python floats are also IEEE-754 doubles.
+_PHP_INT_MAX: Final[int] = 9223372036854775807
+_PHP_INT_MIN: Final[int] = -9223372036854775808
+_PHP_INT_MAX_AS_FLOAT: Final[float] = float(_PHP_INT_MAX)
+
+# Strict decimal check — deliberately NOT a generic "is this numeric" check: '0x1A' /
+# '1_000' must not be silently turned into a number. Reference: contextIsDecimal().
+_DECIMAL_RE: Final[re.Pattern[str]] = re.compile(r"^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$")
+
+# A bare integer literal (no '.', no exponent) — parsed as an exact Python int first, so
+# a large-but-in-range integer never round-trips through float and loses precision.
+# Reference: the `filter_var($str, FILTER_VALIDATE_INT)` branch of contextCastInt().
+_INT_LITERAL_RE: Final[re.Pattern[str]] = re.compile(r"^[+-]?\d+$")
+
+# ---------------------------------------------------------------------------
+# The rule table — ported 1:1 from LogManager::$contextTypeRules. Entries are matched
+# lowercased (except 'reserved', see _resolve_type), so must be supplied lowercase.
+# ---------------------------------------------------------------------------
+
+# ESCAPE HATCH — top of the resolution chain, beats every other bucket including
+# 'reserved'. LAST segment only. Name a key '*_int'/'*_float'/'*_bool' to force a type:
+# it is the one rule nothing else can override.
+_SUFFIX_RULES: Final[Mapping[str, str]] = MappingProxyType(
+    {
+        "int": CONTEXT_TYPE_INT,
+        "float": CONTEXT_TYPE_FLOAT,
+        "bool": CONTEXT_TYPE_BOOL,
+    }
+)
+
+# Fields this library writes itself — pinned so a string default can't regress them.
+# Looked up by the RAW key first, then the lowercased key (see _resolve_type) — this is
+# why LOGGER_SKIP_TRACE ('skipTrace', camelCase) is stored camelCase here rather than
+# lowercased like every other entry: the raw-key pass is the only pass that can ever
+# match it (the lowercased pass looks for the literal key 'skiptrace', not stored here).
+_RESERVED_RULES: Final[Mapping[str, str]] = MappingProxyType(
+    {
+        "log_type": CONTEXT_TYPE_STRING,
+        "file": CONTEXT_TYPE_STRING,
+        "tag": CONTEXT_TYPE_STRING,
+        "trace": CONTEXT_TYPE_SKIP,
+        LOGGER_SKIP_TRACE: CONTEXT_TYPE_SKIP,
+        "exception": CONTEXT_TYPE_STRING,
+        "exception_code": CONTEXT_TYPE_INT,
+        "exception_prev": CONTEXT_TYPE_STRING,
+        "exception_prev_message": CONTEXT_TYPE_STRING,
+        "exception_prev_file": CONTEXT_TYPE_STRING,
+        "exception_prev_code": CONTEXT_TYPE_INT,
+        "exception_prev_trace": CONTEXT_TYPE_STRING,
+        # The one id that is NOT an auto-increment integer: a UUID (or the incoming
+        # X-Request-ID) is written here on every record. Pinned, not left to the "uncastable
+        # falls back to string" fallback — that fallback holds only until some caller passes
+        # an all-digit request id, at which point the field would diverge across records.
+        "request_id": CONTEXT_TYPE_STRING,
+    }
+)
+
+# Whole-key overrides — the only way to type a key whose segments carry no type word.
+_EXACT_RULES: Final[Mapping[str, str]] = MappingProxyType(
+    {
+        # Last segment 'mctime' is not a word (would collide with the int 'time' rule).
+        LOGGER_MCTIME: CONTEXT_TYPE_FLOAT,
+        # memory_get_usage()-equivalents — both int; 'usage'/'peak' are too generic to be words.
+        LOGGER_MEMORY: CONTEXT_TYPE_INT,
+        LOGGER_MEMORY_PEAK: CONTEXT_TYPE_INT,
+        # Legacy key from the sibling logger. 'millisecond' is deliberately NOT a word —
+        # 'seconds' is the canonical unit.
+        "millisecond": CONTEXT_TYPE_INT,
+    }
+)
+
+# LAST segment => type. The type WORDS themselves live in 'suffix' above, which wins over
+# this bucket: 'price_int' is an int, not a float.
+_WORD_RULES: Final[Mapping[str, str]] = MappingProxyType(
+    {
+        # Covers the bare key 'id' and every '*_id'. An identifier is treated as an
+        # auto-increment integer, wanted for range queries and aggregations. A non-integer
+        # id (UUID, hash, hex) must be pinned to string via 'exact' — see 'request_id' above.
+        "id": CONTEXT_TYPE_INT,
+        "count": CONTEXT_TYPE_INT,
+        "cnt": CONTEXT_TYPE_INT,
+        "num": CONTEXT_TYPE_INT,
+        "qty": CONTEXT_TYPE_INT,
+        "total": CONTEXT_TYPE_INT,
+        # A counted sum, not money — money is 'money'/'amount'/'price' (float).
+        "sum": CONTEXT_TYPE_INT,
+        "size": CONTEXT_TYPE_INT,
+        "bytes": CONTEXT_TYPE_INT,
+        "len": CONTEXT_TYPE_INT,
+        "length": CONTEXT_TYPE_INT,
+        "limit": CONTEXT_TYPE_INT,
+        "offset": CONTEXT_TYPE_INT,
+        "page": CONTEXT_TYPE_INT,
+        "depth": CONTEXT_TYPE_INT,
+        "attempt": CONTEXT_TYPE_INT,
+        "retries": CONTEXT_TYPE_INT,
+        "level": CONTEXT_TYPE_INT,
+        "port": CONTEXT_TYPE_INT,
+        "status": CONTEXT_TYPE_INT,
+        # TRAP: '*_time' TRUNCATES a sub-second value — name it '*_duration'/'*_seconds'.
+        "time": CONTEXT_TYPE_INT,
+        "seconds": CONTEXT_TYPE_INT,
+        "ttl": CONTEXT_TYPE_INT,
+        # The money words. 'total'/'sum' are int — money must use one of these.
+        "money": CONTEXT_TYPE_FLOAT,
+        "amount": CONTEXT_TYPE_FLOAT,
+        "price": CONTEXT_TYPE_FLOAT,
+        "duration": CONTEXT_TYPE_FLOAT,
+        "rate": CONTEXT_TYPE_FLOAT,
+        "ratio": CONTEXT_TYPE_FLOAT,
+        "percent": CONTEXT_TYPE_FLOAT,
+        "avg": CONTEXT_TYPE_FLOAT,
+        "score": CONTEXT_TYPE_FLOAT,
+        "flag": CONTEXT_TYPE_BOOL,
+        "enabled": CONTEXT_TYPE_BOOL,
+        "success": CONTEXT_TYPE_BOOL,
+        # No "force string" list: string IS the default. NOTE: 'word' outranks 'prefix', so
+        # a bool prefix loses to a typed last segment — 'is_bot_id' is an INT, not a bool.
+    }
+)
+
+# FIRST segment => type, only for keys with more than one segment (a lone 'is' is a word,
+# not a prefix), and only when the last segment resolved nothing.
+_PREFIX_RULES: Final[Mapping[str, str]] = MappingProxyType(
+    {
+        "is": CONTEXT_TYPE_BOOL,
+        "has": CONTEXT_TYPE_BOOL,
+        "can": CONTEXT_TYPE_BOOL,
+        "should": CONTEXT_TYPE_BOOL,
+        "allow": CONTEXT_TYPE_BOOL,
+        "enable": CONTEXT_TYPE_BOOL,
+        "use": CONTEXT_TYPE_BOOL,
+    }
+)
+
+_KNOWN_BUCKETS: Final[frozenset[str]] = frozenset({"suffix", "reserved", "exact", "word", "prefix"})
+_SEGMENT_BUCKETS: Final[frozenset[str]] = frozenset({"suffix", "word", "prefix"})
+
+_SNAKE_ACRONYM_RE: Final[re.Pattern[str]] = re.compile(r"([A-Z]+)([A-Z][a-z])")
+_SNAKE_BOUNDARY_RE: Final[re.Pattern[str]] = re.compile(r"([a-z0-9])([A-Z])")
+
+
+def _to_snake_case(key: str) -> str:
+    """camelCase/PascalCase -> snake_case, then lowercase.
+
+    §4.7 opt-in key normalization (`PylogConfig.snake_case`), reference `Str::snake()`
+    (Laravel). This is a standard two-pass camelCase splitter, not a byte-for-byte port
+    of `Str::snake()`'s own per-character lookahead regex: for the tested/common case
+    (single hump, e.g. 'orderId' -> 'order_id') the two agree exactly; for a run of
+    consecutive capitals (an acronym, e.g. 'HTTPStatus') they diverge — this produces
+    'http_status', while Laravel's `Str::snake()` produces 'h_t_t_p_status'. Deliberate:
+    `snake_case` is off by default and untested against acronym keys in the reference
+    suite, and porting `Str::snake()`'s exact algorithm (cache, custom delimiter, full
+    Unicode `ucwords` semantics) buys nothing for this contract that the common-case
+    conversion doesn't already cover. Flagged here rather than silently diverging.
+    """
+    s = _SNAKE_ACRONYM_RE.sub(r"\1_\2", key)
+    s = _SNAKE_BOUNDARY_RE.sub(r"\1_\2", s)
+    return s.lower()
+
+
+def _merge_extra_rules(buckets: dict[str, dict[str, str]], extra: Mapping[str, Mapping[str, str]]) -> None:
+    """Merge project-declared rules on top of `buckets`, in place.
+
+    Reference: `LogManager::addContextTypeRules()`. An unknown bucket name or an
+    unrecognized type value is skipped silently — a config typo must not break logging.
+    A 'suffix'/'word'/'prefix' pattern is trimmed of leading/trailing underscores and
+    must reduce to a single segment (no embedded underscore) or it is dropped: those
+    buckets can only ever match one `_`-delimited segment, and 'exact' is what types a
+    whole key. 'reserved' patterns are kept in their given case (see _RESERVED_RULES);
+    every other bucket's pattern is lowercased, matching `contextResolveType()`'s
+    lowercased lookups.
+    """
+    for bucket, entries in extra.items():
+        if bucket not in _KNOWN_BUCKETS:
+            continue
+        for pattern, rtype in entries.items():
+            if rtype not in _VALID_TYPES:
+                continue
+            normalized = str(pattern)
+            if bucket != "reserved":
+                normalized = normalized.lower()
+            if bucket in _SEGMENT_BUCKETS:
+                normalized = normalized.strip("_")
+                if normalized == "" or "_" in normalized:
+                    continue
+            buckets[bucket][normalized] = rtype
+
+
+def _scalar_to_string(value: bool | int | float | str) -> str:
+    """Stringify a scalar the way PHP's `(string)` cast does — used only for the
+    "no rule matched" / plain-string-typed fallback, never for the JSON-encode path
+    (`_json_encode` below), which already gets Python's own float formatting for free.
+
+    - bool -> 'true'/'false' (`(string) false === ''` would look like a missing value).
+    - float -> PHP's `(string)` cast drops a trailing '.0' on a whole-number float
+      (`(string) 5.0 === '5'`); Python's `str()` always keeps it (`str(5.0) == '5.0'`).
+      Matched here for wire-CONTENT parity with the PHP fleet — both land in a string
+      field either way, so this is a content nuance, not a type-stability break.
+    - int -> `str()`, EXCEPT: CPython bounds base-10 int<->str conversion to ~4300
+      digits by default (a DoS guard added in 3.11+) and raises `ValueError` past it.
+      PHP has no such limit (and no native PHP int can even reach this magnitude —
+      it is bounded to 64 bits), so there is no reference behaviour to match; this
+      is a Python-only edge case. The contract that matters is "never raise out of
+      the logging path", so a bounded, deterministic placeholder is emitted instead.
+    """
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, float):
+        return str(int(value)) if math.isfinite(value) and value.is_integer() else str(value)
+    if isinstance(value, int):
+        try:
+            return str(value)
+        except ValueError:
+            return f"<int:{value.bit_length()}-bit>"
+    return value
+
+
+def _cap_string(value: str) -> str:
+    """Cap a string to `CONTEXT_MAX_STRING_BYTES` UTF-8 bytes, truncating on a character
+    boundary (never splitting a multi-byte sequence) and appending an ellipsis, mirroring
+    PHP's `strlen()`/`mb_strcut()` pairing (`contextCapString()`).
+    """
+    encoded = value.encode("utf-8", errors="replace")
+    if len(encoded) <= CONTEXT_MAX_STRING_BYTES:
+        return encoded.decode("utf-8")
+    truncated = encoded[: CONTEXT_MAX_STRING_BYTES - 1].decode("utf-8", errors="ignore")
+    return truncated + "…"
+
+
+def _cap_depth(value: object, depth: int) -> object:
+    """Replace any container nested past `_CONTEXT_JSON_MAX_DEPTH` with a placeholder.
+
+    Pre-processing pass for `_json_encode`: guards against unbounded recursion / huge
+    blobs the same way PHP's depth-bounded `json_encode()` does, but by truncating
+    BEFORE encoding rather than retrying encode-then-salvage — simpler, and it can never
+    itself raise `RecursionError`.
+    """
+    if depth >= _CONTEXT_JSON_MAX_DEPTH:
+        return "…" if isinstance(value, Mapping | list | tuple | set | frozenset) else value
+    if isinstance(value, Mapping):
+        return {str(k): _cap_depth(v, depth + 1) for k, v in value.items()}
+    if isinstance(value, list | tuple | set | frozenset):
+        return [_cap_depth(v, depth + 1) for v in value]
+    return value
+
+
+def _json_encode(value: object) -> str:
+    """Best-effort, never-raising JSON encoding for a structure/object placed under a
+    scalar coercion rule (reference `contextJsonEncode()`; `(int) [1, 2] === 1` would
+    silently lose data, so the value is encoded instead of cast).
+
+    Compact separators (no spaces) to match PHP `json_encode()`'s default formatting;
+    `ensure_ascii=True` to match PHP's default of NOT setting `JSON_UNESCAPED_UNICODE`.
+    One accepted formatting non-parity: PHP additionally backslash-escapes `/` by
+    default (no `JSON_UNESCAPED_SLASHES`); Python's `json` module has no equivalent
+    knob and this is not worth a custom encoder for a value that is itself an opaque,
+    already-a-string context field, not the outer wire envelope.
+    """
+    try:
+        capped = _cap_depth(value, 0)
+        encoded = json.dumps(capped, ensure_ascii=True, separators=(",", ":"), default=str)
+    except Exception:
+        encoded = json.dumps({"_encode_error": type(value).__name__})
+    return _cap_string(encoded)
+
+
+def _cast_int(value: bool | int | float | str) -> int | str:
+    """Reference `contextCastInt()`. A fractional value truncates rather than falling
+    back to string, so `retries => 1.5` and `retries => 3` don't diverge in type; a
+    value that would overflow the PHP int64 boundary falls back to string instead of
+    wrapping into garbage (see `_PHP_INT_MAX`).
+    """
+    if isinstance(value, bool):
+        return 1 if value else 0
+    if isinstance(value, int):
+        if _PHP_INT_MIN <= value <= _PHP_INT_MAX:
+            return value
+        return _cap_string(_scalar_to_string(value))
+    if isinstance(value, float):
+        if not math.isfinite(value) or value >= _PHP_INT_MAX_AS_FLOAT or value <= -_PHP_INT_MAX_AS_FLOAT:
+            return _cap_string(_scalar_to_string(value))
+        return int(value)  # truncates toward zero, like PHP's (int) cast
+    stripped = value.strip()
+    if not _DECIMAL_RE.match(stripped):
+        # (int) 'RU' === 0 would destroy the value — fall back to the default type.
+        return _cap_string(value)
+    if _INT_LITERAL_RE.match(stripped):
+        try:
+            as_int = int(stripped)
+        except ValueError:
+            # CPython bounds base-10 str->int conversion to ~4300 digits by default
+            # (a DoS guard, 3.11+) and raises past it. PHP's `filter_var` has no such
+            # limit, but it already returns false for anything past PHP_INT_MAX — a
+            # 4300+ digit literal is WAY past that too, so both languages converge on
+            # the same float-then-range-check fallback below either way. Fall through.
+            pass
+        else:
+            if _PHP_INT_MIN <= as_int <= _PHP_INT_MAX:
+                # Exact for every integer literal in range — no float round-trip to lose bits.
+                return as_int
+            # Out of PHP-int range as a bare literal: fall through to the float path
+            # below, mirroring `filter_var(..., FILTER_VALIDATE_INT)` returning false.
+    # Fractional ('19.99'), exponent ('1e5'), or out of int range. `float()` has no
+    # digit-count limit (unlike `int()`) — it overflows cleanly to +-inf instead.
+    num = float(stripped)
+    if not math.isfinite(num) or num >= _PHP_INT_MAX_AS_FLOAT or num <= -_PHP_INT_MAX_AS_FLOAT:
+        return _cap_string(value)
+    return int(num)
+
+
+def _cast_float(value: bool | int | float | str) -> float | str:
+    """Reference `contextCastFloat()`."""
+    if isinstance(value, bool):
+        return 1.0 if value else 0.0
+    if isinstance(value, float):
+        return value if math.isfinite(value) else _cap_string(_scalar_to_string(value))
+    if isinstance(value, int):
+        try:
+            return float(value)
+        except OverflowError:
+            return _cap_string(_scalar_to_string(value))
+    stripped = value.strip()
+    if not _DECIMAL_RE.match(stripped):
+        return _cap_string(value)
+    num = float(stripped)
+    return num if math.isfinite(num) else _cap_string(value)
+
+
+def _cast_bool(value: bool | int | float | str) -> bool:
+    """Reference `contextCastBool()`."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int | float):
+        return value != 0
+    return value.strip().lower() not in CONTEXT_FALSE_VALUES
+
+
+def _cast_value(value: object, rtype: str | None) -> object:
+    """Reference `contextCastValue()`. `None` always stays `None`. A structure
+    (dict/list/tuple/set/frozenset — the Python analogue of a PHP array) is left
+    untouched when no rule matched (flattening it would break nested-path queries) and
+    JSON-encoded when a scalar rule matched (a scalar cast would silently drop data).
+    Any other non-primitive object (custom class instance, Decimal, Enum, ...) is
+    treated the same way as a structure: PHP's own `contextCastValue()` routes every
+    `is_object()` value through the identical array/object branch (its narrower
+    `Stringable`-under-an-explicit-`string`-rule shortcut has no clean Python analogue —
+    Python has no `Stringable`-equivalent formal marker distinct from "every object has
+    `__str__`" — so it is not replicated; documented here rather than silently dropped).
+    """
+    if value is None:
+        return None
+    if isinstance(value, Mapping | list | tuple | set | frozenset):
+        return value if rtype is None else _json_encode(value)
+    if isinstance(value, bool | int | float | str):
+        if rtype == CONTEXT_TYPE_INT:
+            return _cast_int(value)
+        if rtype == CONTEXT_TYPE_FLOAT:
+            return _cast_float(value)
+        if rtype == CONTEXT_TYPE_BOOL:
+            return _cast_bool(value)
+        # No rule, or an explicit 'string' rule: both stringify — string is the default.
+        return _cap_string(_scalar_to_string(value))
+    return value if rtype is None else _json_encode(value)
+
+
+class ContextTypeCorrector:
+    """Precompiled context field type-coercion table.
+
+    Construct once per process (or once per `PylogConfig`, via `from_config`) — the
+    merged rule buckets are built at construction, not per call, since this sits on the
+    hot logging path. `correct()` returns a NEW dict; it never mutates its input.
+
+    Does not perform credential redaction — that's `log_python.redactor.Redactor`, wired in
+    together with this at the `manager.py` orchestration layer (a later phase), exactly
+    as the PHP reference's `contextTypeCorrector()` calls `Redactor::shouldRedactKey()`
+    inline. Kept separate here so the coercion table has no dependency on the redactor.
+    """
+
+    __slots__ = ("_buckets", "_snake_case")
+
+    def __init__(self, extra_rules: Mapping[str, Mapping[str, str]] = MappingProxyType({}), *, snake_case: bool = False) -> None:
+        buckets: dict[str, dict[str, str]] = {
+            "suffix": dict(_SUFFIX_RULES),
+            "reserved": dict(_RESERVED_RULES),
+            "exact": dict(_EXACT_RULES),
+            "word": dict(_WORD_RULES),
+            "prefix": dict(_PREFIX_RULES),
+        }
+        _merge_extra_rules(buckets, extra_rules)
+        self._buckets: Mapping[str, Mapping[str, str]] = MappingProxyType({bucket: MappingProxyType(entries) for bucket, entries in buckets.items()})
+        self._snake_case = snake_case
+
+    @classmethod
+    def from_config(cls, config: PylogConfig) -> ContextTypeCorrector:
+        """Build a corrector whose extra rules and snake_case flag come from `PylogConfig`.
+
+        `config.context_type_rules` merges ON TOP of the built-in table (never
+        replaces it) — same semantics as `LogManager::addContextTypeRules()`.
+        """
+        return cls(config.context_type_rules, snake_case=config.snake_case)
+
+    @property
+    def rules(self) -> Mapping[str, Mapping[str, str]]:
+        """The merged rule buckets (`suffix`/`reserved`/`exact`/`word`/`prefix`), read-only."""
+        return self._buckets
+
+    def resolve_type(self, key: str) -> str | None:
+        """Resolve `key` to a type constant, or `None` when nothing matched (the caller
+        then defaults to string). Reference `contextResolveType()`; first match wins:
+        suffix > reserved (raw key, then lowercased) > exact > word > prefix.
+        """
+        low = key.lower()
+        # Whole segments only: 'report' splits into ['report'], never matches 'port'.
+        parts = low.split("_")
+        last = parts[-1]
+
+        suffix = self._buckets["suffix"]
+        if last in suffix:
+            return suffix[last]
+        reserved = self._buckets["reserved"]
+        if key in reserved:
+            return reserved[key]
+        if low in reserved:
+            return reserved[low]
+        exact = self._buckets["exact"]
+        if low in exact:
+            return exact[low]
+        word = self._buckets["word"]
+        if last in word:
+            return word[last]
+        # A single-segment key has no prefix: a lone 'is' is a word, not a flag.
+        if len(parts) > 1:
+            prefix = self._buckets["prefix"]
+            if parts[0] in prefix:
+                return prefix[parts[0]]
+        return None
+
+    def correct(self, context: Mapping[str, object]) -> dict[str, object]:
+        """Return a new dict with every value coerced per the resolved type of its key.
+
+        §4.7: when `snake_case` is on, keys are normalized BEFORE rule resolution (same
+        order as the reference) — the whole mapping is renamed in one pass, then each
+        (possibly renamed) key is resolved and its value cast independently.
+
+        Every key is coerced with `str(key)` before it is used, for lookup AND as the
+        output key — mirroring the reference's own `(string) $k` cast at each of its
+        three key-consuming call sites (`shouldRedactKey`, `contextResolveType`,
+        `Str::snake`). The declared signature already commits to string keys; this is
+        defensive fidelity for an untyped caller (mypy protects typed ones), not a
+        widened contract — a non-string key is coerced, never a crash.
+        """
+        working: Mapping[str, object] = context
+        if self._snake_case:
+            working = {_to_snake_case(str(k)): v for k, v in context.items()}
+
+        result: dict[str, object] = {}
+        for raw_key, value in working.items():
+            key = raw_key if isinstance(raw_key, str) else str(raw_key)
+            rtype = self.resolve_type(key)
+            if rtype == CONTEXT_TYPE_SKIP:
+                result[key] = value
+                continue
+            result[key] = _cast_value(value, rtype)
+        return result