flechtwerk 0.1.0__py3-none-any.whl

flechtwerk/__init__.py

@@ -0,0 +1,20 @@
+"""Flechtwerk — async stream processing framework for Kafka."""
+from .configs import ConfigStore
+from .extractor import Extractor
+from .module import CompressionType, Flechtwerk, MqttBrokerConfig
+from .transformer import Transformer
+from .types import Config, Event, IncomingMessage, Message, State
+
+__all__ = [
+    "CompressionType",
+    "Config",
+    "ConfigStore",
+    "Event",
+    "Extractor",
+    "Flechtwerk",
+    "IncomingMessage",
+    "Message",
+    "MqttBrokerConfig",
+    "State",
+    "Transformer",
+]

flechtwerk/attribute/__init__.py

@@ -0,0 +1,50 @@
+"""Type-safe handles on dict keys, paired with explicit encode/decode codecs."""
+from .attribute import (
+    Attribute,
+    MissingAttributeError,
+    RawDict,
+)
+from .codec import Codec, Decoder, Encoder
+from .codecs import (
+    BOOL,
+    DATE,
+    DATETIME,
+    DICT,
+    FLOAT,
+    INT,
+    LIST,
+    SET,
+    STR,
+    TIME,
+    TUPLE,
+)
+from .record import (
+    ANY,
+    RECORD,
+    Record,
+    record_codec,
+)
+
+__all__ = [
+    "ANY",
+    "Attribute",
+    "BOOL",
+    "Codec",
+    "DATE",
+    "DATETIME",
+    "DICT",
+    "Decoder",
+    "Encoder",
+    "FLOAT",
+    "INT",
+    "LIST",
+    "MissingAttributeError",
+    "RawDict",
+    "RECORD",
+    "Record",
+    "SET",
+    "STR",
+    "TIME",
+    "TUPLE",
+    "record_codec",
+]

flechtwerk/attribute/attribute.py

@@ -0,0 +1,173 @@
+"""Type-safe handles on keys in a dict, with a paired encode/decode codec.
+
+`Attribute(name, codec)` declares a required field; `Attribute(name, codec,
+optional=True)` declares one that may be absent or `None`. The keyword-only
+`optional` flag drives exactly one write-side guard: a required attribute
+rejects `None` writes (so a missing value can't land silently as JSON
+`null`), an optional attribute stores `None` as `null`. Read semantics are
+identical for both kinds and are carried by the *method*, not the flag —
+`Record[attr]` reads-or-raises (returns `V`), `Record.get` / `Record.pop`
+tolerate absence (return `V | None`). The `required` property is the
+inverse of `optional`, for the few sites that branch on mandatory-ness
+(e.g. a validation layer's missing-field check).
+
+Each `Attribute` carries a `Codec[V]` that drives both the static type
+parameter and the runtime encode/decode. The type checker infers the
+`[V]` from the codec — `Attribute("name", STR)` produces an
+`Attribute[str]` without an explicit subscript. Built-in codecs are
+exported from `flechtwerk.attribute` (`STR`, `INT`, `DATETIME`, `RECORD`,
+`LIST(RECORD)`, …).
+"""
+from typing import Any
+
+from .codec import Codec
+from .codecs import IDENTITY
+
+type RawDict = dict[str, Any]
+"""Wire-form JSON-native dict — the underlying storage of `Record.raw` and the
+argument type for every `Attribute` dict-op (`read_from`, `write_to`, …)."""
+
+
+class MissingAttributeError(KeyError):
+    """Raised by `Attribute.read_from` when the value is absent or `None`."""
+
+
+class Attribute[V]:
+    """A typed handle on one key in a `RawDict`, paired with an encode/decode codec.
+
+    `optional=False` (the default) declares a required field whose
+    `write_to` rejects `None`; `optional=True` allows `None` (stored as
+    JSON `null`). The read methods are kind-agnostic — which presence
+    semantic applies is chosen by the caller's method (`[]` vs
+    `.get` / `.pop`), not by this flag.
+
+    Public attributes:
+
+    - `name`: the wire-level dict key this attribute reads/writes.
+    - `codec`: the `Codec[V]` driving encode/decode. Exposed so callers can
+      compose codecs (e.g. `LIST(some_attr.codec)` lifts an attribute's
+      codec into a list-of-V codec). Direct encode/decode access goes
+      through `attr.codec.encode` / `attr.codec.decode`; the Attribute
+      itself only surfaces dict-operating methods (`read_from`,
+      `write_to`, `present_in`, `delete_from`, `get_from`, `pop_from`).
+    - `optional`: whether `None` / absence is permitted on write.
+    """
+
+    def __init__(self, name: str, codec: Codec[V], *, optional: bool = False) -> None:
+        self.name = name
+        self.codec = codec
+        self.optional = optional
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Reject subclasses outside this module — the Attribute hierarchy is sealed."""
+        super().__init_subclass__(**kwargs)
+        if cls.__module__ != Attribute.__module__:
+            raise TypeError(f"{cls.__qualname__} cannot extend the sealed Attribute hierarchy")
+
+    @property
+    def required(self) -> bool:
+        """Whether this attribute must be present and non-`None` — the inverse of `optional`."""
+        return not self.optional
+
+    def read_from(self, raw: RawDict) -> V:
+        """Look up this attribute in `raw` and return the decoded value.
+
+        Raises `MissingAttributeError` if the key is absent or the stored
+        value is `None`. This is kind-agnostic — a `[]` read raises on
+        absence regardless of `optional`; absence-tolerance lives in
+        `Record.get` / `Record.pop`.
+        """
+        # Null ≡ missing is duplicated in get_from and pop_from — change all in lockstep.
+        v = raw.get(self.name)
+        if v is None:
+            raise MissingAttributeError(f"attribute {self!r} is missing")
+        return self.codec.decode(v)
+
+    def write_to(self, raw: RawDict, value: V | None) -> None:
+        """Encode `value` and store it under this attribute's name in `raw`.
+
+        A required attribute (`optional=False`) rejects `None` at the
+        write-site so it can't land silently as JSON `null`; an optional
+        attribute stores `None` as `null`. The `not self.optional` check
+        rides the `None` branch only, so the common non-`None` write pays
+        nothing for it.
+        """
+        if value is None:
+            if not self.optional:
+                raise ValueError(f"cannot assign None to required {self!r}")
+            raw[self.name] = None
+        else:
+            raw[self.name] = self.codec.encode(value)
+
+    def present_in(self, raw: RawDict) -> bool:
+        """Whether this attribute is present in `raw` (key exists, value may be `None`)."""
+        return self.name in raw
+
+    def delete_from(self, raw: RawDict) -> None:
+        """Remove this attribute's entry from `raw`. Raises `KeyError` if absent."""
+        del raw[self.name]
+
+    def get_from(self, raw: RawDict, default: V | None = None) -> V | None:
+        """Return the decoded value, or `default` if missing or `None`."""
+        v = raw.get(self.name)
+        return self.codec.decode(v) if v is not None else default
+
+    def pop_from(self, raw: RawDict, *default: V) -> V | None:
+        """Remove and return the decoded value; raise `KeyError` if missing and no default.
+
+        A stored `None` is returned as `None` (no decode), and the key is
+        removed — mirroring `dict.pop` semantics for `None` writes.
+        """
+        if not self.present_in(raw):
+            if default:
+                return default[0]
+            raise KeyError(self)
+        v = raw.get(self.name)
+        if v is not None:
+            v = self.codec.decode(v)
+        self.delete_from(raw)
+        return v
+
+    # Identity is (type, name) — never the codec or `optional`. The name is the
+    # wire key this handle addresses, so two handles for the same slot are equal.
+    # The codec is excluded on purpose: codecs compare by object identity, so a
+    # composite codec like LIST(STR) is rebuilt per call and would make
+    # "same field" attributes unequal. `type` is in the key so a ViewAttribute
+    # stays distinct from a plain Attribute of the same name — the dict-spread
+    # override relies on both write_to calls running, the typed one landing last.
+    def __eq__(self, other: object) -> bool:
+        return type(other) is type(self) and other.name == self.name  # type: ignore[attr-defined]
+
+    def __hash__(self) -> int:
+        return hash((type(self), self.name))
+
+    def __repr__(self) -> str:
+        kind = ", optional=True" if self.optional else ""
+        return f"{type(self).__name__}({self.name!r}{kind})"
+
+
+class ViewAttribute(Attribute[Any]):
+    """Synthesized view onto a `Record` key, produced by `Record.keys()`.
+
+    Overrides `read_from` (raw passthrough, None-tolerant) and `write_to`
+    (identity store, no encoding) — the spread roundtrip must list
+    every key including stored JSON "null", and the value coming back
+    in is already in wire form. The same dispatch protocol as every other
+    Attribute, just with no-op codec behavior.
+
+    Public class but deliberately not re-exported from `flechtwerk.attribute`:
+    application code constructs handles via `Attribute(...)`; `ViewAttribute`
+    is a framework-internal mechanism that powers `Record`'s dict-spread
+    support. Reaching it requires the fully qualified import, which serves
+    as the "you know what you're doing" signal in lieu of the leading
+    underscore.
+    """
+
+    def __init__(self, name: str):
+        super().__init__(name, IDENTITY)
+
+    def read_from(self, raw: RawDict) -> Any:
+        return raw[self.name]
+
+    def write_to(self, raw: RawDict, value: Any) -> None:
+        raw[self.name] = value

flechtwerk/attribute/codec.py

@@ -0,0 +1,31 @@
+"""The `Codec[V]` dataclass — paired encode/decode for a Python value of type `V`.
+
+`Attribute[V]` is constructed with a `Codec[V]`. Both directions are required:
+the codec is the single source of truth for how a `V` round-trips through
+JSON-native form. The `[V]` type parameter on `Attribute` is inferred from
+the codec by the type checker — there's no runtime type introspection.
+
+Built-in codec constants (`STR`, `INT`, `DATETIME`, `RECORD`, …) live in
+`codecs.py`.
+"""
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+type Decoder[V] = Callable[[Any], V]
+"""A function that decodes a JSON-native wire value to a Python value of type `V`."""
+
+type Encoder[V] = Callable[[V], Any]
+"""A function that encodes a Python value of type `V` to a JSON-native wire value."""
+
+
+@dataclass(frozen=True, slots=True)
+class Codec[V]:
+    """A pair of `(decode, encode)` callables for a value of type `V`.
+
+    Both directions are required — there is no fallback registry. The value
+    type `V` is the single source of truth: pass a `Codec[V]` to an
+    `Attribute` and the type checker infers the `Attribute[V]` parameter.
+    """
+    decode: Decoder[V]
+    encode: Encoder[V]

flechtwerk/attribute/codecs.py

@@ -0,0 +1,140 @@
+"""Built-in codec atoms and constructors.
+
+The catalogue is composable: atoms (`STR`, `INT`, `BOOL`, `DATE`, `FLOAT`,
+`DATETIME`, `TIME`) are fixed leaves; constructors (`LIST`, `SET`, `TUPLE`,
+`DICT`) take an inner codec and return a parameterized container codec.
+Element validation is uniform — `LIST(STR).encode([1, 2, 3])` rejects
+non-strings (each element runs through `STR.encode`).
+
+`RECORD` and `ANY` live in `record.py` because they need the `Record`
+class and the recursive `_encode_any` walker, respectively.
+
+Naming convention: all atoms and constructors use uppercase identifiers
+matching the ALL_CAPS style of the typed-attribute call sites.
+"""
+from datetime import date, datetime, time
+from typing import Any, Final
+
+from .codec import Codec, Decoder
+
+
+def _encode_datetime(dt: datetime) -> str:
+    """Encoder for `DATETIME` — lossless `isoformat` defaults, `Z` for UTC.
+
+    Default `isoformat` precision (full microseconds when nonzero, no
+    fraction when zero) keeps the encoder lossless — a fixed `timespec`
+    would silently truncate sub-millisecond values and break round-trips.
+
+    The `Z` suffix replaces `+00:00` only when the zone *is* UTC
+    (`tzname() == "UTC"` — matches `timezone.utc`, `ZoneInfo("UTC")` and
+    plain `timezone(timedelta(0))`). A zone that merely coincides with UTC
+    (e.g. `Europe/London` in winter, `tzname() == "GMT"`) keeps its
+    `+00:00` offset — `Z` asserts UTC, not a zero offset.
+    """
+    encoded = dt.isoformat()
+    return encoded.replace("+00:00", "Z") if dt.tzname() == "UTC" else encoded
+
+
+def _validate[T](t: type[T]) -> Decoder[T]:
+    """Codec helper that asserts `type(x) is t`.
+
+    Exact-type check, not `isinstance` — this matters for the int/bool split
+    (`bool` is a subclass of `int`, but `INT.encode(True)` should reject).
+    Statically enforced by the `Codec[T]` parameter at the call site; the
+    runtime `assert` is a safety net that disappears under `python -O`.
+    """
+
+    def check(x: Any) -> T:
+        assert type(x) is t, f"expected {t.__name__}, got {type(x).__name__}: {x!r}"
+        return x
+
+    return check
+
+
+# --- atoms ---
+
+
+STR: Final = Codec[str](_validate(str), _validate(str))
+INT: Final = Codec[int](_validate(int), _validate(int))
+BOOL: Final = Codec[bool](_validate(bool), _validate(bool))
+DATE: Final = Codec[date](date.fromisoformat, date.isoformat)
+FLOAT: Final = Codec[float](_validate(float), _validate(float))
+DATETIME: Final = Codec[datetime](datetime.fromisoformat, _encode_datetime)
+TIME: Final = Codec[time](time.fromisoformat, time.isoformat)
+
+
+# --- constructors ---
+
+
+def LIST[V](inner: Codec[V]) -> Codec[list[V]]:
+    """Codec for `list[V]` — runs `inner` over each element."""
+    return Codec(
+        decode=lambda lst: [inner.decode(x) for x in lst],
+        encode=lambda lst: [inner.encode(x) for x in lst],
+    )
+
+
+def SET[V](inner: Codec[V]) -> Codec[set[V]]:
+    """Codec for `set[V]` — runs `inner` over each element.
+
+    Encode emits a sorted list (deterministic wire form for diff stability).
+    Sort is on raw values, then each is encoded — preserves the natural
+    ordering of the source type. V must be hashable (a Python set
+    requirement) and the raw values must be comparable to each other.
+    """
+    return Codec(
+        decode=lambda items: {inner.decode(x) for x in items},
+        encode=lambda s: [inner.encode(x) for x in sorted(s)],
+    )
+
+
+def TUPLE[V](inner: Codec[V]) -> Codec[tuple[V, ...]]:
+    """Codec for `tuple[V, ...]` — runs `inner` over each element, preserves order."""
+    return Codec(
+        decode=lambda items: tuple(inner.decode(x) for x in items),
+        encode=lambda t: [inner.encode(x) for x in t],
+    )
+
+
+def DICT[V](inner: Codec[V]) -> Codec[dict[str, V]]:
+    """Codec for `dict[str, V]` — runs `inner` over each value.
+
+    Keys must be exactly `str` — enforced statically by the
+    `dict[str, V]` parameter and asserted at runtime via exact-type
+    check (same discipline as `_validate`). Str subclasses (e.g.
+    `StrEnum` members) are rejected — accepting them silently would
+    lose type information at the boundary.
+    """
+
+    def encode(d: dict[str, V]) -> dict[str, Any]:
+        for k in d:
+            assert type(k) is str, f"DICT key must be str, got {type(k).__name__}: {k!r}"
+        return {k: inner.encode(v) for k, v in d.items()}
+
+    return Codec(
+        decode=lambda d: {k: inner.decode(v) for k, v in d.items()},
+        encode=encode,
+    )
+
+
+IDENTITY: Final = Codec[Any](decode=lambda x: x, encode=lambda x: x)
+"""Identity codec — used by `ViewAttribute` where the value is already in wire form.
+
+Deliberately not re-exported from `flechtwerk.attribute`: an application
+that wants pass-through behavior should declare a real codec for the
+underlying type rather than reach for `IDENTITY`. Available via the
+fully-qualified import for the framework internals that need it.
+"""
+
+__all__ = [
+    "BOOL",
+    "DATETIME",
+    "DICT",
+    "FLOAT",
+    "INT",
+    "LIST",
+    "SET",
+    "STR",
+    "TIME",
+    "TUPLE",
+]

flechtwerk/attribute/record.py

@@ -0,0 +1,265 @@
+"""A typed dict wrapper, keyed exclusively by `Attribute` objects.
+
+`Record` wraps an underlying `dict[str, Any]` (exposed as `raw`) whose
+string keys serialize directly to JSON. All public access uses
+`Attribute` instances:
+
+    event[CHANNEL_ID]              # decoded V, or raise if absent/null
+    event[CHANNEL_ID] = value      # dispatches via attr.write_to
+    event.get(STATUS, default)     # decoded V or default
+    event.pop(LAST_TIME, default)  # decoded V or default
+    del event[STATUS]              # removes the entry
+    STATUS in event                # presence check
+
+Indexing with a string raises `TypeError`. The *method* encodes the
+presence intent — `[]` asserts the value is present (returns `V`),
+`.get()` / `.pop()` tolerate absence (return `V | None`) — independent
+of whether the attribute was declared `optional`.
+
+Iteration (`iter(record)`, `for attr in record`) yields the same
+synthesized `ViewAttribute` handles that `keys()` produces — aligning
+with the standard `Mapping` convention that `iter(d) == iter(d.keys())`.
+Use `record.raw` directly if you need the wire-form key strings.
+
+Dict-spread is supported (`Record({**other_record, NEW_ATTR: value})`):
+``keys()`` yields `ViewAttribute` handles that override `read_from`
+(raw passthrough, None-tolerant) and `write_to` (identity store) so the
+spread roundtrip flows through the standard Record paths without any
+special-casing in Record itself.
+"""
+from collections.abc import Iterable, Iterator
+from copy import deepcopy
+from datetime import date, datetime, time
+from typing import Any, Final, Self, overload
+
+from .attribute import (
+    Attribute,
+    RawDict,
+    ViewAttribute,
+)
+from .codec import Codec
+from .codecs import DATE, DATETIME, DICT, LIST, SET, TIME, TUPLE
+
+
+def _encode_any(v: Any) -> Any:
+    """Recursively encode any value to JSON-native form via isinstance dispatch.
+
+    Walks dicts/lists/sets/tuples through their `(ANY)` codecs; converts
+    `datetime` to ISO 8601, `date` to ISO 8601 (`YYYY-MM-DD`), `time` to
+    ISO 8601 (`HH:MM:SS[.ffffff]`), `Record` to a shallow copy of its
+    `raw`. The JSON-native primitives
+    (`str`, `int`, `float`, `bool`, `None`) pass through unchanged.
+    Raises `TypeError` on any other type — silent passthrough would let
+    non-JSON-native values land in `Record.raw` and crash later in
+    `json.dumps`.
+
+    This is the implementation of `ANY.encode` and the runtime-dispatch
+    layer that container codecs delegate into when their inner is `ANY`.
+    """
+    if v is None:
+        return v
+    if isinstance(v, (str, int, float)):  # bool ⊂ int — passes through as bool
+        return v
+    if isinstance(v, datetime):
+        return DATETIME.encode(v)
+    if isinstance(v, date):  # datetime ⊂ date — must come after the datetime check
+        return DATE.encode(v)
+    if isinstance(v, time):
+        return TIME.encode(v)
+    if isinstance(v, Record):
+        return RECORD.encode(v)
+    if isinstance(v, dict):
+        return _DICT_OF_ANY.encode(v)
+    if isinstance(v, list):
+        return _LIST_OF_ANY.encode(v)
+    if isinstance(v, set):
+        return _SET_OF_ANY.encode(v)
+    if isinstance(v, tuple):
+        return _TUPLE_OF_ANY.encode(v)
+    raise TypeError(f"no encoder for {type(v).__name__}: {v!r}")
+
+
+class Record:
+    """Wrapper around a `RawDict` with `Attribute`-only access."""
+
+    raw: RawDict
+
+    def __init__(self, source: Record | dict[Attribute, Any] | None = None, /) -> None:
+        self.raw = {}
+        if source is None:
+            return
+        if isinstance(source, Record):
+            self.raw = source.raw.copy()
+            return
+        for k, v in source.items():
+            k.write_to(self.raw, v)
+
+    @classmethod
+    def wrap(cls, source: RawDict, /) -> Self:
+        self = cls()
+        for k, v in source.items():
+            self.raw[k] = _encode_any(v)
+        return self
+
+    def __reduce__(self) -> tuple:
+        # Pickle reconstructs via (cls.wrap, (raw,)), running back through the
+        # wire-format path. copy.copy/deepcopy do not ride this — they use the
+        # dedicated __copy__/__deepcopy__ below.
+        return self.__class__.wrap, (self.raw,)
+
+    # --- indexing ---
+
+    def __getitem__[V](self, attr: Attribute[V]) -> V:
+        return attr.read_from(self.raw)
+
+    def __setitem__[V](self, attr: Attribute[V], value: V | None) -> None:
+        attr.write_to(self.raw, value)
+
+    def __delitem__(self, attr: Attribute) -> None:
+        """Remove the key from the underlying dict. Raises `KeyError` if absent."""
+        attr.delete_from(self.raw)
+
+    def __contains__(self, attr: Attribute) -> bool:
+        """Check key presence — kind-agnostic, since a question neither decodes
+        a value nor mutates the absence contract."""
+        return attr.present_in(self.raw)
+
+    # --- container protocol ---
+
+    def __len__(self) -> int:
+        return len(self.raw)
+
+    def __iter__(self) -> Iterator[Attribute[Any]]:
+        """Yield a `ViewAttribute` per key in `raw`, lazily.
+
+        The primary iteration protocol — `keys()` materializes this for
+        the dict-spread path. Aligns with Python's dict idiom where
+        `__iter__` is the fundamental lazy walk and `keys()` is the
+        view-returning convenience.
+        """
+        for name in self.raw:
+            yield ViewAttribute(name)
+
+    def keys(self) -> Iterable[Attribute[Any]]:
+        """Materialize a list of `ViewAttribute` handles from `__iter__`.
+
+        Enables dict-spread: ``Record({**other, NEW_ATTR: value})`` calls
+        ``other.keys()`` and then ``other[view_attr]`` for each — both
+        landing on the view's overridden read/write methods. The constructor
+        stores the values as-is via ``ViewAttribute.write_to``.
+        """
+        return list(self)
+
+    def __bool__(self) -> bool:
+        return bool(self.raw)
+
+    # --- equality, repr, copy, hash ---
+
+    def __eq__(self, other: object) -> bool:
+        return type(other) is type(self) and self.raw == other.raw  # type: ignore[attr-defined]
+
+    # Defining `__eq__` implicitly sets `__hash__ = None`, marking the class
+    # unhashable — no need to spell it out.
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.raw!r})"
+
+    def __copy__(self) -> Record:
+        return type(self)(self)
+
+    def __deepcopy__(self, memo: dict) -> Record:
+        new = type(self)()
+        new.raw = deepcopy(self.raw, memo)
+        return new
+
+    # --- Pythonic helpers ---
+
+    @overload
+    def get[V](self, attr: Attribute[V]) -> V | None:
+        ...
+
+    @overload
+    def get[V](self, attr: Attribute[V], default: V) -> V:
+        ...
+
+    def get[V](self, attr: Attribute[V], default: V | None = None) -> V | None:
+        """Return the decoded value, or `default` if missing or `None`."""
+        return attr.get_from(self.raw, default)
+
+    def pop[V](self, attr: Attribute[V], /, *default: V) -> V | None:
+        """Remove and return the decoded value; raise KeyError if missing and no default given.
+
+        A stored `None` is returned as `None` (no decode) and the key is removed —
+        mirroring `dict.pop` semantics and matching how an optional attribute's
+        `write_to` allows `None` writes.
+        """
+        return attr.pop_from(self.raw, *default)
+
+    def coalesce[V](self, *attrs: Attribute[V]) -> V | None:
+        """Return the first non-`None` decoded value among the given attributes.
+
+        Equivalent to a chain of `.get()` falls-through: returns
+        `.get(attrs[0])` if present, else `.get(attrs[1])`, ..., else
+        `None`. Useful for wire formats where the same logical field
+        appears under several names (e.g. pagination variants like
+        `pages` vs `total_page` vs `total_pages`).
+        """
+        for attr in attrs:
+            v = attr.get_from(self.raw)
+            if v is not None:
+                return v
+        return None
+
+    def update(self, other: Record) -> None:
+        """Merge another `Record` into this one."""
+        self.raw.update(other.raw)
+
+
+def record_codec[T: Record](cls: type[T]) -> Codec[T]:
+    """Build a `Codec[T]` for a `Record` subclass `T`.
+
+    Decode wraps the raw dict in `cls`; encode returns a shallow copy of
+    `.raw`. Top-level isolation is preserved (the new owner gets its own
+    dict to mutate via `__setitem__`); nested dicts/lists are shared,
+    matching the framework's "treat `.raw` as immutable from outside"
+    contract.
+    """
+    return Codec(
+        decode=cls.wrap,
+        encode=lambda r: r.raw.copy(),
+    )
+
+
+RECORD: Final = record_codec(Record)
+"""Codec for an untyped `Record` value.
+
+Use as `Attribute("data", RECORD)` for fields whose value is a
+plain `Record`. For `Record` subclasses, build a per-subclass codec via
+`record_codec(cls)` (or use the constants exported from `flechtwerk.types`
+for `Config`, `Event`, `State`).
+"""
+
+ANY: Final = Codec[Any](
+    decode=lambda x: x,
+    encode=_encode_any,
+)
+"""The universal escape-hatch codec for `Any`-typed values.
+
+Decode is identity (the wire value passes through unchanged — JSON load
+already produced JSON-native shape). Encode runs the recursive
+`_encode_any` walker, which dispatches on runtime type and handles
+`Record`, `dict`, `list`, `set`, `tuple`, `datetime`, `date`, `time`,
+and the JSON-native primitives.
+
+Compose with the container constructors for typed-but-heterogeneous
+fields: `LIST(DICT(ANY))` for `list[dict[str, Any]]`, `DICT(ANY)` for
+`dict[str, Any]`, etc.
+"""
+
+# Pre-built bare-Any container codecs, used by `_encode_any`'s isinstance
+# dispatch. Building these once at module load time avoids reconstructing a
+# fresh `Codec` per recursive call.
+_DICT_OF_ANY: Final = DICT(ANY)
+_LIST_OF_ANY: Final = LIST(ANY)
+_SET_OF_ANY: Final = SET(ANY)
+_TUPLE_OF_ANY: Final = TUPLE(ANY)