Skip to content

Envelope module docstring claims a frozen pydantic model but the config sets frozen=False #54

@nficano

Description

@nficano

src/arcp/_envelope.py:1 documents the module as "8 fields, arcp constant, frozen pydantic model" and src/arcp/_envelope.py:27 repeats "Outer envelope for every wire frame. 8 fields per spec §5.1." But the actual configuration at src/arcp/_envelope.py:29 is model_config = ConfigDict(extra="allow", frozen=False, populate_by_name=True), so envelopes are mutable. The runtime takes advantage of mutability indirectly via Envelope.model_copy(update=...) at src/arcp/_runtime/session.py:107 and src/arcp/_runtime/_handlers.py:308, both of which work regardless of frozen. The docstring/configuration mismatch will mislead a reader who is trying to reason about whether they can mutate an envelope before forwarding it, and pyright cannot warn on accidental in-place mutation because the config explicitly opts out. Either the docstring is stale, or frozen=True was the intent and the configuration regressed during a refactor.

Fix prompt: Decide which side is correct. If the envelope is conceptually frozen per spec §5.1, change the config to frozen=True, run the test suite to verify nothing relies on in-place mutation, and update the few code paths that need to produce a modified envelope to use model_copy(update=...) (they already do). If the envelope is intentionally mutable for performance reasons, remove "frozen pydantic model" from the module docstring at src/arcp/_envelope.py:1 and the class docstring at src/arcp/_envelope.py:27, and replace it with a one-line note explaining why mutability is preserved (for example, in-place event_seq stamping). Add a one-line test that asserts the chosen mutability via attempting env.id = "..." and either expects success or ValidationError.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationseverity:lowLow severity

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions