orjson 3.11.9: dumps, loads, OPT_INDENT_2

# CSX Sample Notes: orjson Serialization, Deserialization, and Contract Invariants

## Prior Knowledge Search
`search_known_solution` returned a MISS for `pkg:pypi/orjson@3.11.9` (pass rate 0.00 across 2 prior failure observations). Existing network verified samples target `orjson@3.12.0`.

This sample establishes the canonical clean-room reference contract for `pkg:pypi/orjson@3.11.9`.

## Pinned Release and Scope
- Package: `orjson==3.11.9`
- Ecosystem: PyPI (Python)

## What a Model Would Have Written Instead
A model would have:
1. Written `orjson.dumps(data, indent=2, sort_keys=True)` assuming standard library `json` keyword arguments and `str` return type.
2. Expected `orjson.dumps(data, default=...)` to automatically intercept primitive subclasses (e.g. `SecretStr(str)`) and `@dataclass` instances without enabling `OPT_PASSTHROUGH_SUBCLASS` and `OPT_PASSTHROUGH_DATACLASS`.
3. Assumed non-string dictionary keys (e.g., `{1: "val"}`) serialize by default or through the `default` serializer callback.
4. Expected `orjson.loads()` to transparently accept UTF-8 Byte Order Mark (BOM) prefixes and file-like stream objects (e.g. `io.BytesIO`).
5. Assumed `orjson.dumps()` emits Python stdlib non-standard `NaN` and `Infinity` literals instead of RFC 8259-compliant JSON `null`.

## How the Wrong Version Fails
1. Passing standard library keyword arguments raises `TypeError: dumps() got an unexpected keyword argument 'indent'` (or `sort_keys`).
2. Without `OPT_PASSTHROUGH_SUBCLASS` and `OPT_PASSTHROUGH_DATACLASS`, `orjson` natively serializes primitive subclasses and dataclasses, completely bypassing custom `default` serializer hooks and silently leaking raw values or unmasked secrets.
3. Passing non-string dictionary keys without `OPT_NON_STR_KEYS` raises `TypeError: Dict key must be str` (`orjson.JSONEncodeError`), completely ignoring `default` callables.
4. Passing UTF-8 BOM headers to `orjson.loads()` fails with `orjson.JSONDecodeError` rather than stripping them.
5. Passing stream objects to `orjson.loads()` fails with `orjson.JSONDecodeError: Input must be bytes, bytearray, memoryview, or str`.
6. `orjson.dumps()` converts non-finite floats (`nan`, `inf`, `-inf`) strictly to JSON `null`, and `orjson.loads()` strictly rejects non-standard `NaN` / `Infinity` literals.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify orjson in pkg:pypi/orjson@3.11.9
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/orjson@3.11.9
Demonstrate these symbols/APIs:
  - orjson
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:95d3c34f270164de32f4d6d41a1e72eb583b158433a88e47920862425887fca4","constraints":{"executionContext":"python"},"contract":["assert orjson.dumps strictly returns bytes and rejects standard library keyword arguments with TypeError","assert formatting and sorting require bitwise-ORed option integer bitmasks (OPT_INDENT_2, OPT_SORT_KEYS, OPT_APPEND_NEWLINE)","assert non-string dict keys raise JSONEncodeError/TypeError by default and require OPT_NON_STR_KEYS","assert dataclasses, datetime, and uuid.UUID are natively serialized without custom serializers","assert primitive subclasses, dataclasses, and datetimes bypass the default serializer hook unless OPT_PASSTHROUGH_* flags are enabled","assert non-finite floats (NaN, Inf, -Inf) are serialized to JSON null conforming to RFC 8259","assert OPT_STRICT_INTEGER allows integers within 53-bit range while integers exceeding 2**53-1 raise JSONEncodeError/TypeError","assert orjson.Fragment embeds pre-serialized JSON buffers and raises TypeError during dumps if content is not bytes or str","assert orjson.loads accepts bytes, bytearray, memoryview, and str while rejecting streams and UTF-8 BOM headers with JSONDecodeError","assert orjson.JSONDecodeError subclasses ValueError and json.JSONDecodeError, and JSONEncodeError subclasses TypeError"],"goal":"verify orjson in pkg:pypi/orjson@3.11.9","kind":"HOW","packages":["pkg:pypi/orjson@3.11.9"],"schemaVersion":1,"symbols":["orjson","orjson.dumps","orjson.loads","orjson.OPT_INDENT_2","orjson.OPT_SORT_KEYS","orjson.OPT_NON_STR_KEYS","orjson.OPT_UTC_Z","orjson.OPT_APPEND_NEWLINE","orjson.OPT_PASSTHROUGH_SUBCLASS","orjson.OPT_PASSTHROUGH_DATACLASS","orjson.OPT_PASSTHROUGH_DATETIME","orjson.OPT_STRICT_INTEGER","orjson.Fragment","orjson.JSONDecodeError","orjson.JSONEncodeError"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","ecosystem":"pypi","executionContext":"python","language":"python","os":"linux","packageManager":"pip","runtime":"python","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/orjson@3.11.9"],"schemaVersion":1,"subject":"pkg:pypi/orjson@3.11.9","symbols":["orjson","orjson.dumps","orjson.loads","orjson.OPT_INDENT_2","orjson.OPT_SORT_KEYS","orjson.OPT_NON_STR_KEYS","orjson.OPT_UTC_Z","orjson.OPT_APPEND_NEWLINE","orjson.OPT_PASSTHROUGH_SUBCLASS","orjson.OPT_PASSTHROUGH_DATACLASS","orjson.OPT_PASSTHROUGH_DATETIME","orjson.OPT_STRICT_INTEGER","orjson.Fragment","orjson.JSONDecodeError","orjson.JSONEncodeError"],"verifierAdapter":"python@1"}

orjson==3.11.9

{
  "schemaVersion": 1,
  "goal": "verify orjson in pkg:pypi/orjson@3.11.9",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/orjson@3.11.9"
  ],
  "symbols": [
    "orjson"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

"""orjson serialization and deserialization utility package."""

from .serializer import (
    deserialize,
    format_datetime,
    serialize,
    serialize_to_str,
)

__all__ = [
    "deserialize",
    "format_datetime",
    "serialize",
    "serialize_to_str",
]

"""Production serialization and deserialization helpers wrapping orjson."""

from typing import Any, Callable, Optional, Union
import datetime
import orjson


def serialize(
    obj: Any,
    *,
    pretty: bool = False,
    sort_keys: bool = False,
    non_str_keys: bool = False,
    utc_z: bool = False,
    naive_utc: bool = False,
    append_newline: bool = False,
    strict_integer: bool = False,
    passthrough_subclass: bool = False,
    passthrough_dataclass: bool = False,
    passthrough_datetime: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
) -> bytes:
    """Serialize a Python object to UTF-8 encoded JSON bytes.

    Key invariants:
    - Returns strictly `bytes`, never `str`.
    - Options are combined as an integer bitmask via the singular `option=` keyword.
    - Dicts with non-string keys require `OPT_NON_STR_KEYS`.
    - Subclasses, dataclasses, and datetimes bypass the `default` hook unless
      the corresponding `OPT_PASSTHROUGH_*` flag is set.
    """
    option = 0
    if pretty:
        option |= orjson.OPT_INDENT_2
    if sort_keys:
        option |= orjson.OPT_SORT_KEYS
    if non_str_keys:
        option |= orjson.OPT_NON_STR_KEYS
    if utc_z:
        option |= orjson.OPT_UTC_Z
    if naive_utc:
        option |= orjson.OPT_NAIVE_UTC
    if append_newline:
        option |= orjson.OPT_APPEND_NEWLINE
    if strict_integer:
        option |= orjson.OPT_STRICT_INTEGER
    if passthrough_subclass:
        option |= orjson.OPT_PASSTHROUGH_SUBCLASS
    if passthrough_dataclass:
        option |= orjson.OPT_PASSTHROUGH_DATACLASS
    if passthrough_datetime:
        option |= orjson.OPT_PASSTHROUGH_DATETIME

    if option != 0:
        return orjson.dumps(obj, default=default, option=option)
    return orjson.dumps(obj, default=default)


def serialize_to_str(
    obj: Any,
    *,
    pretty: bool = False,
    sort_keys: bool = False,
    non_str_keys: bool = False,
    utc_z: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
) -> str:
    """Serialize a Python object to a decoded UTF-8 string."""
    return serialize(
        obj,
        pretty=pretty,
        sort_keys=sort_keys,
        non_str_keys=non_str_keys,
        utc_z=utc_z,
        default=default,
    ).decode("utf-8")


def format_datetime(
    dt: datetime.datetime,
    *,
    utc_z: bool = False,
    naive_utc: bool = False,
) -> bytes:
    """Format a datetime instance to RFC 3339 / ISO 8601 JSON bytes."""
    option = 0
    if utc_z:
        option |= orjson.OPT_UTC_Z
    if naive_utc:
        option |= orjson.OPT_NAIVE_UTC
    if option != 0:
        return orjson.dumps(dt, option=option)
    return orjson.dumps(dt)


def deserialize(payload: Union[bytes, bytearray, memoryview, str]) -> Any:
    """Deserialize JSON bytes, bytearray, memoryview, or str into Python objects."""
    return orjson.loads(payload)

"""Contract test proving orjson 3.11.9 behaviors and invariants."""

import dataclasses
import datetime
import decimal
import io
import json
from pathlib import Path
import sys
import uuid
import zoneinfo

sys.path.insert(0, str(Path(__file__).resolve().parents[1]))

import orjson
from src.serializer import (
    deserialize,
    format_datetime,
    serialize,
    serialize_to_str,
)


@dataclasses.dataclass
class AccountRecord:
    account_id: int
    owner: str
    created_at: datetime.datetime


class SecretToken(str):
    pass


def custom_serializer(obj):
    if isinstance(obj, SecretToken):
        return "***REDACTED***"
    if isinstance(obj, AccountRecord):
        return {"id": obj.account_id, "user": obj.owner.upper()}
    if isinstance(obj, datetime.datetime):
        return obj.strftime("%Y/%m/%d")
    if isinstance(obj, decimal.Decimal):
        return str(obj)
    raise TypeError(f"Type {type(obj)} not serializable")


def test_contract() -> None:
    # 1. orjson.dumps return type and rejection of stdlib keyword arguments
    sample_data = {"key": "value", "count": 42}
    dumped_bytes = orjson.dumps(sample_data)
    assert isinstance(dumped_bytes, bytes)
    assert dumped_bytes == b'{"key":"value","count":42}'

    # Rejection of standard library json keyword arguments
    for invalid_kwargs in [
        {"indent": 2},
        {"sort_keys": True},
        {"separators": (",", ":")},
        {"options": orjson.OPT_INDENT_2},  # 'options' plural raises TypeError
    ]:
        try:
            orjson.dumps(sample_data, **invalid_kwargs)
            raise AssertionError(f"Expected orjson.dumps to reject invalid kwargs: {invalid_kwargs}")
        except TypeError:
            pass

    # 2. Option bitmasks: formatting, sorting, and append newline
    formatted = serialize(
        {"b": 2, "a": 1},
        pretty=True,
        sort_keys=True,
        append_newline=True,
    )
    assert formatted == b'{\n  "a": 1,\n  "b": 2\n}\n'

    # serialize_to_str returns str
    str_result = serialize_to_str({"a": 1})
    assert isinstance(str_result, str)
    assert str_result == '{"a":1}'

    # 3. Non-string dictionary keys
    int_dict = {100: "first", 200: "second"}
    try:
        orjson.dumps(int_dict)
        raise AssertionError("Expected orjson.dumps to reject non-str keys by default")
    except (orjson.JSONEncodeError, TypeError):
        pass

    encoded_non_str = serialize(int_dict, non_str_keys=True)
    assert encoded_non_str == b'{"100":"first","200":"second"}'

    # 4. Native types: UUID, Datetime, Dataclass
    test_uuid = uuid.UUID("a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d")
    utc_dt = datetime.datetime(2025, 6, 1, 12, 0, 0, tzinfo=datetime.timezone.utc)
    record = AccountRecord(account_id=42, owner="test_user", created_at=utc_dt)

    native_dump = orjson.dumps({"id": test_uuid, "record": record, "time": utc_dt})
    assert b'"a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"' in native_dump
    assert b'"account_id":42' in native_dump
    assert b'"owner":"test_user"' in native_dump
    assert b'"2025-06-01T12:00:00+00:00"' in native_dump

    # 5. Default serializer hook and passthrough options
    secret = SecretToken("top_secret_auth_token")

    # Without OPT_PASSTHROUGH_SUBCLASS, default hook is bypassed and secret leaks
    leaked = orjson.dumps({"token": secret}, default=custom_serializer)
    assert leaked == b'{"token":"top_secret_auth_token"}'

    # With passthrough_subclass, default serializer intercepts subclass
    redacted = serialize(
        {"token": secret},
        passthrough_subclass=True,
        default=custom_serializer,
    )
    assert redacted == b'{"token":"***REDACTED***"}'

    # Dataclass passthrough
    dc_transformed = serialize(
        {"record": record},
        passthrough_dataclass=True,
        default=custom_serializer,
    )
    assert dc_transformed == b'{"record":{"id":42,"user":"TEST_USER"}}'

    # Datetime passthrough
    dt_transformed = serialize(
        {"time": utc_dt},
        passthrough_datetime=True,
        default=custom_serializer,
    )
    assert dt_transformed == b'{"time":"2025/06/01"}'

    # 6. Non-finite float serialization (RFC 8259 null conversion)
    floats_payload = {"nan": float("nan"), "inf": float("inf"), "ninf": float("-inf")}
    assert orjson.dumps(floats_payload) == b'{"nan":null,"inf":null,"ninf":null}'

    # 7. OPT_STRICT_INTEGER (53-bit range validation)
    max_safe_int = (1 << 53) - 1
    min_safe_int = -((1 << 53) - 1)
    unsafe_int = 1 << 53

    safe_int_bytes = serialize({"safe": max_safe_int, "min": min_safe_int}, strict_integer=True)
    assert safe_int_bytes == b'{"safe":9007199254740991,"min":-9007199254740991}'

    try:
        serialize({"unsafe": unsafe_int}, strict_integer=True)
        raise AssertionError("Expected strict_integer to reject integers > 2**53-1")
    except (orjson.JSONEncodeError, TypeError):
        pass

    # 8. orjson.Fragment raw buffer splicing
    frag = orjson.Fragment(b'{"cached": true}')
    fragment_dump = orjson.dumps({"status": "ok", "payload": frag})
    assert fragment_dump == b'{"status":"ok","payload":{"cached": true}}'

    invalid_frag = orjson.Fragment(9999)  # type: ignore
    try:
        orjson.dumps({"f": invalid_frag})
        raise AssertionError("Expected orjson.dumps to reject Fragment with non-bytes/str")
    except TypeError as exc:
        assert "not of type bytes or str" in str(exc)

    # 9. orjson.loads input support and rejection of BOM and streams
    assert deserialize(b'{"key": "val"}') == {"key": "val"}
    assert deserialize(bytearray(b'{"key": "val"}')) == {"key": "val"}
    assert deserialize(memoryview(b'DATA_{"key": "val"}_CHECKSUM')[5:19]) == {"key": "val"}
    assert deserialize('{"key": "val"}') == {"key": "val"}

    # Rejection of UTF-8 BOM
    try:
        deserialize(b"\xef\xbb\xbf{\"key\": \"val\"}")
        raise AssertionError("Expected orjson.loads to reject UTF-8 BOM")
    except orjson.JSONDecodeError as exc:
        assert issubclass(type(exc), orjson.JSONDecodeError)

    # Rejection of file-like stream objects
    try:
        deserialize(io.BytesIO(b'{"key": "val"}'))  # type: ignore
        raise AssertionError("Expected orjson.loads to reject stream objects")
    except orjson.JSONDecodeError:
        pass

    # Rejection of invalid non-finite float literals
    for bad_literal in [b'{"val": NaN}', b'{"val": Infinity}', b'{"val": -Infinity}']:
        try:
            deserialize(bad_literal)
            raise AssertionError(f"Expected orjson.loads to reject {bad_literal}")
        except orjson.JSONDecodeError:
            pass

    # 10. Exception hierarchy
    assert issubclass(orjson.JSONDecodeError, ValueError)
    assert issubclass(orjson.JSONDecodeError, json.JSONDecodeError)
    assert issubclass(orjson.JSONEncodeError, TypeError)


if __name__ == "__main__":
    test_contract()