# `duron.codec` module

A codec converts application values to JSON for persistence and reconstructs them when read. Select a codec on the workflow; its effects and ports use the same codec.

## Default codec

`DefaultCodec` encodes finite JSON values and returns decoded JSON unchanged. It accepts `None`, `bool`, `int`, finite `float`, `str`, lists of JSON values, and dictionaries with string keys. Tuples, bytes, dates, dataclasses, and model objects require a custom codec. `NaN` and infinities are rejected, including inside containers. Only exact built-in JSON types are accepted; subclasses such as enums need a custom codec. Strings must be valid UTF-8. Cyclic containers, nesting beyond 64 container levels, and integers exceeding 4096 bits are rejected.

## Type validation

The default codec itself does not validate annotations or reconstruct Python types. The runtime wraps the selected codec with checks at workflow, effect, and port boundaries. Values must match their declared types. Missing annotations and `Any` allow arbitrary values supported by the codec.

`Codec.decode_json` is generic: given `TypeHint[T]`, it must return `T` or raise if it cannot decode the value. Duron validates decoded values and checks that encoded values can be decoded to the declared type before committing them. A custom codec must reconstruct external data as needed; its decoder can run during encoding and must be free of external side effects. Validation checks type conformance, not equality of the original and reconstructed objects.

## Implement a custom codec

A codec must encode every value it handles as finite JSON and reconstruct values according to the supplied type hint. Select one codec on the workflow; it handles workflow and effect arguments and results and port payloads. Duron handles its own runtime metadata separately.

```python
from dataclasses import dataclass
from typing import TypeVar, cast

import duron
from duron.codec import DefaultCodec, JSONValue, TypeHint

T = TypeVar("T")


@dataclass(frozen=True)
class Order:
    number: str


class OrderCodec:
    def encode_json(
        self, value: object, annotated_type: TypeHint[object], /
    ) -> JSONValue:
        if isinstance(value, Order):
            return {"number": value.number}
        return DefaultCodec.encode_json(value, annotated_type)

    def decode_json(self, encoded: JSONValue, expected_type: TypeHint[T], /) -> T:
        if expected_type is Order:
            if not isinstance(encoded, dict) or not isinstance(
                encoded.get("number"), str
            ):
                raise TypeError("invalid encoded order")
            return cast(T, Order(encoded["number"]))
        return DefaultCodec.decode_json(encoded, expected_type)


@duron.workflow(codec=OrderCodec())
async def echo(ctx: duron.WorkflowContext, order: Order) -> Order:
    return order


async def example() -> None:
    async with duron.SQLiteScheduler(":memory:", workflows=[echo]) as scheduler:
        for _ in range(2):
            run = await scheduler.submit(echo, "order", Order("A-1"))
            assert await run.result() == Order("A-1")
```

This codec handles an `Order` as a directly annotated value. Supporting `list[Order]`, unions, or nested models requires recursive handling of those type hints; the fallback to `DefaultCodec` does not add it.

## Evolve a codec

Effects can be reused by workflows with different codecs. Make `decode_json` accept previously persisted wire values as the format evolves, using in-band version tags when needed. Duron does not fingerprint codec implementations. Choose a new workflow name and run ID for incompatible changes. Remote adapters must preserve the active workflow's serialization contract.

## Encode failure details

For structured failure details, explicitly encode a value with the codec and pass the JSON to `ApplicationError(..., details=...)`. When catching the error, decode `error.details` with the application schema. Exception objects are never passed to the workflow codec.

Serialization contracts: the `Codec` protocol and the default JSON codec.

## JSONValue

```python
JSONValue: TypeAlias
```

Recursive type representing any valid JSON value.

## TypeHint

```python
TypeHint
```

A type expression or the internal unspecified-type sentinel.

## \_MAX\_DEPTH

```python
_MAX_DEPTH
```

## \_MAX\_INT\_BITS

```python
_MAX_INT_BITS
```

## \_T

```python
_T
```

## \_\_all\_\_

```python
__all__
```

## Codec

Protocol for encoding/decoding Python objects to/from JSON-serializable values.

Implement this protocol to provide custom serialization for types not supported by the default codec (e.g., dataclasses, Pydantic models, custom objects). Select it on the workflow to encode application values throughout that run. Runtime framing uses fixed JSON. Incompatible encoding changes require a new workflow name. Decoding must return the type described by the supplied hint or raise; workflow code trusts this generic contract. The codec can be used explicitly for structured `ApplicationError.details`. Runtime error metadata uses fixed JSON; exception objects are never passed to the codec.

### decode\_json

```python
decode_json(
    encoded: JSONValue, expected_type: TypeHint[_T]
) -> _T
```

Reconstruct a Python object from a JSON value during log replay.

Parameters:

- **`encoded`** (`JSONValue`) –

  The JSON value to decode
- **`expected_type`** (`TypeHint[_T]`) –

  Type hint for the expected return type

Returns:

- `_T` –

  The reconstructed Python object

### encode\_json

```python
encode_json(
    result: object, annotated_type: TypeHint[object]
) -> JSONValue
```

Convert a Python object to a JSON-serializable value for persistence.

Parameters:

- **`result`** (`object`) –

  The object to encode (e.g., operation result or argument)
- **`annotated_type`** (`TypeHint[object]`) –

  Type hint for the object's type

Returns:

- `JSONValue` –

  A JSON-serializable value (None, bool, int, float, str, list, or dict)

Raises:

- `TypeError` –

  If the object cannot be serialized

## DefaultCodec

Encode finite JSON values and return decoded values unchanged.

Supports `None`, booleans, numbers, strings, lists, and dictionaries with string keys. Annotations do not trigger type validation or reconstruction. Use a custom Codec for other Python types.

### decode\_json

```python
decode_json(
    encoded: JSONValue, _expected_type: TypeHint[_T]
) -> _T
```

### encode\_json

```python
encode_json(
    result: object, _annotated_type: TypeHint[object]
) -> JSONValue
```

## \_check\_json

```python
_check_json(
    x: object, depth: int, active: set[int]
) -> bool
```

## \_is\_json\_value

```python
_is_json_value(x: object) -> TypeGuard[JSONValue]
```

Return whether `x` is a finite, canonical JSON-serializable value.

Only exact builtin types qualify, so enum and other subclasses are rejected rather than silently decoded as their base type. Strings must be valid UTF-8 (no lone surrogates), integers are bounded, nesting is limited to a fixed depth, and cyclic containers are rejected.

Returns:

- `TypeGuard[JSONValue]` –

  True if `x` contains only canonical JSON values and finite floats.

## \_is\_utf8

```python
_is_utf8(value: str) -> bool
```
