symfonic.services.shadow.state

state

Replacement state writes, suppressed.

A shadow run must be able to read what it wrote — otherwise a multi-step invocation diverges for a reason that has nothing to do with the replacement implementation — while the replacement's real state store must be left exactly as it was found.

So writes land in a private overlay and are recorded as intents, reads consult the overlay before the baseline, and the real backing store is never handed to the run at all. The writer keeps a digest of the backing store taken at construction so assert_backing_untouched can prove the claim rather than assert it.

StateWriteIntent dataclass

StateWriteIntent(seq: int, key: str, value_digest: str, deleted: bool = False)

A write the replacement would have performed. Never applied.

SuppressedStateWriter dataclass

SuppressedStateWriter(baseline: Mapping[str, Any] = dict(), backing: Mapping[str, Any] | None = None)

Copy-on-write overlay over a read-only baseline.

assert_backing_untouched

assert_backing_untouched() -> None

Prove the replacement's real store is byte-identical to before.

Source code in src/symfonic/services/shadow/state.py

def assert_backing_untouched(self) -> None:
    """Prove the replacement's real store is byte-identical to before."""
    if self._snapshot() != self._backing_digest:
        raise ShadowAbortedError(
            "the replacement state store changed during a shadow run; the "
            "suppression claim is withheld"
        )