Shadow before cutover

“Shadow before cutover” is not a feature; it is the strategy the whole package encodes. Every class
exists to make that ordering possible and safe. This page argues for it.

Motivation

Authorization is the one subsystem you cannot get wrong silently. A wrong decision either locks out a
legitimate user (an outage you will hear about) or lets in an illegitimate one (a breach you might not).
Both failure modes are unacceptable in production, and both are exactly what a blind authorization switch
risks.

The risk model of a blind switch

Suppose you migrate $n$ permission checks and your mapping has an unknown error rate $p$ per check. The
probability that a big-bang cutover is completely clean is

For even a small per-mapping error rate over a realistic estate this collapses toward zero:

A blind switch is a bet that every mapping is right at once. Shadow mode changes the game: instead of
betting, you measure $p$ on real traffic and drive it to zero before you switch.

The ordering

Observation must precede enforcement because:

1. You cannot measure parity after you switch — once IAM enforces, Spatie is no longer answering real
   checks, so there is nothing to compare against.
2. The cost of a wrong decision is asymmetric and high — measuring is cheap (a log line); a production
   lockout or escalation is not.
3. A reversible switch is only valuable if you know when to use it — the clean diff is the signal that
   says “safe to go”, and the same evidence tells you a regression has appeared if mismatches return.

What a clean diff actually buys you

A clean iam.shadow.mismatch log over representative traffic is a proof of behavioral equivalence on the
paths that occurred:

where $T$ is the set of checks observed in the shadow window. It is empirical, not exhaustive — which is why
the window must be representative (month-end, admin flows, rare roles). But it is evidence from your own
system, which is far stronger than a passing test suite written against assumptions.

How the package enforces the ordering

• Default is shadow. Installing the bridge cannot accidentally enforce anything.
• Shadow returns null from Gate::after. Observation is structurally incapable of changing an outcome.
• Enforce only stops observing. The bridge never flips the authority itself — the client’s Gate adapter
  does — so “enforce” is a deliberate, separate decision.
• Rollback is the same flag. The escape hatch is always one env var away, so attempting the forward move
  is safe.

Next

• Reviewing mismatches — driving the diff to clean.
• Cutover & rollback — the reversible switch the strategy enables.