Skip to content

Add canonical state digest for integrity verification #279

Description

@rlippmann

Summary

Add a stable cryptographic digest for authoritative Engine state so a committed state snapshot has an explicit integrity identity independent of Python's built-in hash() semantics.

Motivation

Python's __hash__() / hash() is intended for hash-table behavior, is not cryptographic, and is not stable across interpreter runs for string-containing values. Context Compiler needs a separate concept if state integrity or stable snapshot identity is to be checked explicitly.

A canonical digest would complement, not replace, immutable state representation.

Architectural direction

  • Derive the digest from a canonical representation of authoritative state.
  • Use a cryptographic digest such as SHA-256 rather than Python's built-in object hash.
  • Exclude the digest value itself from the material being digested.
  • Make the digest deterministic across processes/runs for the same logical state.
  • Compute/update it only when constructing or committing a new authoritative snapshot.
  • Keep the current public state behavior and serialization contract stable unless an explicit persistence-format decision says otherwise.
  • Add tests proving equal canonical states produce equal digests and meaningful state changes produce different digests.

Uses

  • integrity verification / detection of unexpected state mutation;
  • stable state identity for diagnostics or checkpoints;
  • groundwork for later optimistic-concurrency checks.

Boundary

A digest is a detection/identity mechanism, not a same-process security boundary. Code capable of arbitrarily modifying both authoritative state and its stored digest can still bypass it.

Deferred / separate

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