Skip to content

Harden authoritative Engine state against direct mutation #278

Description

@rlippmann

Summary

Strengthen the implementation-level integrity boundary around Engine authoritative state.

The public API already isolates callers from live state through defensive copies and copy/replace transitions, and Engine is slotted. However, the authoritative _state slot currently contains a mutable TypedDict/dict, so code that deliberately reaches into the implementation can mutate working memory directly without going through an Engine transition.

This is implementation-level mutation hardening, not semantic readonly state. Related semantic feature: #197.

Architectural direction

  • Replace mutable _WorkingMemory storage with a deeply immutable value representation, likely a frozen, slotted dataclass or equivalent.
  • Ensure nested policy state is also immutable; a frozen outer object containing a mutable dict is insufficient.
  • Rename the Engine storage attribute from _state to __state so Python name mangling reduces accidental external access and subclass collisions.
  • Preserve the existing copy/construct-and-replace transition model: evaluate against one complete snapshot, construct the next complete snapshot, then replace the authoritative reference.
  • Preserve the existing public premise, policies, import/export, and transition behavior.
  • Add explicit mutation-isolation coverage for authoritative state and nested policy data.

Boundary

This should harden normal Python application semantics; it is not intended to claim tamper resistance against arbitrary hostile code running in the same interpreter. Python name mangling and frozen objects are not a process security boundary.

Deferred / separate

  • cryptographic state digest / integrity identity;
  • locking or optimistic concurrency policy;
  • C/Cython/native storage or process isolation;
  • semantic readonly behavior tracked in Define readonly state semantics #197.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions