Module state_diff_contract 

The deterministic contract behind FeltDB’s semantic state diff.

This is the second specimen of the pattern established by crate::trigger_contract: a decision FeltDB already makes, drawn behind a runtime-independent boundary so that more than one implementation can be held to it.

       canonical state A  +  canonical state B
                       │
        ┌──────────────┴──────────────┐
        │                             │
  native evaluation             WASM evaluation
        │                             │
        └──────────────┬──────────────┘
                       │
              canonical diff bytes

This module adds no diff semantics

SemanticDiff::compute is untouched and remains authoritative. Everything here is envelope: identity, version, canonical encoding, and the decision to report an unusable input rather than fail. If this module and SemanticDiff::compute ever disagree, SemanticDiff::compute is right.

Determinism budget

Evaluation reads nothing but its two states. No clock, filesystem, network, random source, process identity, authentication context, authority metadata or process-global mutable state participates, and the audit that produced this contract found none in the implementation either.

What the audit established about the semantics

These are properties of the existing implementation, recorded here because the contract is defined against them rather than against an idea of what a diff should do:

• Arrays are positional. A reorder is not detected; [1,2] -> [2,1] reports Changed at index 0 and at index 1. Elements past the shorter length become Added or Removed at their index.
• Absence and null are different, in both directions. missing -> value is Added, null -> value is Changed, value -> missing is Removed, value -> null is Changed.
• old_value and new_value are Option, encoded as null when absent. That is ambiguous with a JSON null on its own, and kind is what disambiguates: missing -> null is Added with new_value: null.
• Numbers compare by serde_json variant. 42 and 42.0 differ, so they report Changed; -0 is a float and so differs from the integer 0; -0.0 and 0.0 are equal under IEEE equality and report nothing.
• A type transition is one Changed, carrying both whole values, at the path where it happens — including at the empty path, for the states themselves.
• Ordering is total. Changes sort by path, then by kind. Paths are unique within one diff, so the ordering does not depend on sort stability.

Structs

ContractErrorBody

The error body of a contract output.

StateDiffInput

The complete deterministic input: two states, and the contract’s identity.

StateDiffOutput

The complete deterministic output.

Enums

ContractErrorCode

Why an input could not be evaluated.

ContractRuntime

The runtime that executed a contract, recorded in evidence.

Constants

STATE_DIFF_CONTRACT_ID

Stable identity of this contract.

STATE_DIFF_CONTRACT_VERSION

Version of this contract’s input shape, output shape and semantics.

Functions

canonical_input_bytes

The canonical byte encoding of a contract input.

canonical_output_bytes

The canonical byte encoding of a contract output.

diff_states

The deterministic contract, natively implemented.

evaluate_canonical

The runtime-independent entry point: canonical bytes in, canonical bytes out.

evaluate_canonical_output

evaluate_canonical before encoding, for callers that want the value.

input_digest

Content identity of a contract input, for provenance.