Skip to content

symfonic.services.shadow.ledger

ledger

The effect ledger — what a shadow run tried to do, and what happened.

The ledger is the artifact a reviewer reads to believe the suppression claim. It records attempts, not successes, because the interesting evidence is the call that was denied: a run with an empty ledger proves nothing, and a run whose ledger contains an APPLIED row proves the harness leaked.

EffectAttempt dataclass 

EffectAttempt(seq: int, port_id: str, operation: str, request_digest: str, outcome: EffectOutcome, family: EffectFamily | None = None, externally_visible: bool = True, detail: str = '')

One attempted crossing of a framework effect port.

EffectLedger dataclass 

EffectLedger(entries: list[EffectAttempt] = list())

An append-only record of attempts, in the order they were made.

applied 

applied() -> tuple[EffectAttempt, ...]

Real effects. Must be empty for a shadow run's claim to stand.

Source code in src/symfonic/services/shadow/ledger.py 
76
77
78
def applied(self) -> tuple[EffectAttempt, ...]:
    """Real effects. Must be empty for a shadow run's claim to stand."""
    return self._with(EffectOutcome.APPLIED)

explain 

explain() -> str

A one-line-per-attempt summary safe to log: no payloads, ever.

Source code in src/symfonic/services/shadow/ledger.py 
86
87
88
89
90
91
92
def explain(self) -> str:
    """A one-line-per-attempt summary safe to log: no payloads, ever."""
    return "\n".join(
        f"{e.seq:>3} {e.outcome.value:<12} {e.port_id}.{e.operation} "
        f"[{e.request_digest[:12]}] {e.detail}".rstrip()
        for e in self.entries
    )

EffectOutcome

Bases: StrEnum

How a single attempted effect resolved.