symfonic.services.shadow.effects

effects

SHD-EC — the effect families and the shape of one classification row.

architecture_principles.explicit_effects names the capability families an invocation must declare before it may exercise them (filesystem, cache, network, credential discovery, background tasks, global registration, persistence). T2.3.7 adds the families the runtime itself crosses — provider, tool, pause-token, telemetry, scheduler, plugin, lifecycle — because a shadow run that suppressed only the declared capabilities would still mint a real pause token or export a real span.

The enum is the exhaustiveness axis: a family that exists here and has no classified port is a hole, and :mod:classification refuses to certify it.

EffectFamily

Bases: StrEnum

Every effect family the architecture declares. Exhaustive by contract.

EffectPort dataclass

EffectPort(port_id: str, family: EffectFamily, disposition: ShadowDisposition, rationale: str, externally_visible: bool = True)

One classification row: a port, its family, and its shadow disposition.

rationale is required. A disposition with no recorded reason is a decision nobody can review later, and this table is cutover evidence.

ShadowDisposition

Bases: StrEnum

What shadow mode does with a classified port. There is no third option.

DENY refuses the call. STUB answers it deterministically without reaching anything external. "Let it through" is deliberately not representable — that is the whole point of classifying.