# The shadow league

An agent that writes a rule does not get to switch it on. Every alert, sampling and
log-pipeline rule an **agent principal** creates lands in **shadow**: it is evaluated on live
data, writes would-have rows, and delivers, drops and blocks nothing. After the window a
deterministic grader joins those rows to what people actually did, and the result is the
**promotion card** a person reads before deciding. A shadow nobody promotes expires.

Nothing in this page needs a model. Every number is a count or a ratio over stored rows.

## Landing in shadow

Principal kind decides, never a parameter. A request body that says `lifecycle: LIVE`,
`status: active` or `enabled: true` is not obeyed for an agent.

| Rule | Where it lands | Expires |
| --- | --- | --- |
| Alert rule (REST, MCP, config-as-code) | `lifecycle: SHADOW`, `AlertRule.shadowSince` set | 14 days (`SHADOW_TTL_DAYS`) |
| Span sampling rule (REST) | `status: shadow`, `enabled: false` | 7 days unless the author names an end |
| Log-pipeline rule | by the governed family: `status: shadow` | 7 days |

An agent's own `PATCH` of a sampling rule to `active` is refused. A person's own rule keeps the
behaviour it always had.

## The grade

`runShadowGradePass` (a scheduler step) stores one `ShadowRuleGrade` row per shadow stint of
every alert rule that has been in shadow for a day, upserting on
`(org, kind, rule, windowStart)`, so a re-run changes nothing. The rule's final grade is also
written when it lapses (`runShadowExpiryPass`).

| Figure | Meaning |
| --- | --- |
| `precision` | weighted share of **settled** would-be fires that a person acted on |
| `overlap` | share of settled fires another rule had already raised on the same issue within an hour |
| `pagesPerDay` | would-be fires that would have paged a person, per day of the window |
| `unitsPerDay` | would-have notifications (one per action of a fire), per day of the window |

**Acted on** means, inside seven days after the fire, a *person* resolved, archived or assigned
the issue (`IssueActivity` written by a HUMAN principal: an ownership auto-assignment has no
principal and an agent's act is not ground truth), or a deploy of the same project was a rollback
within 24 hours. The issue's current state is never read.

**Settled** means the fire is a day old, or was already acted on. Younger fires are *pending*:
they count toward the per-day rates and stay out of precision and overlap. That is how the card
is honest at the one-day minimum a rule needs before promotion.

**Attention discount.** An act by a person whom the approver attention report (ACP-16) flagged as
a rubber stamp on that UTC day counts half a fire. A rollback is not an approval and is not
discounted.

**Not joinable.** A fire with no issue and no rollback after it counts as not acted on, and the
card says how many (`unjoinable`): precision is a lower bound for a metric rule. Nothing is
guessed. With no settled fire the stored values are 0 and the card reports no precision.

Sampling and log-pipeline shadow rules keep tallies, not would-have rows, so they have nothing to
join: the readers show their kept and dropped tallies and units per day, `gradeable: false`, and
no grade.

## The promotion card

`shadow_rules_list` and `shadow_rule_get` (read, `project:read`) show the card. `shadow_rules_list`
serves the stored grade whole; `shadow_rule_get`, inside its 500 tokens, serves the grade computed
now with its counts, the stored row as its precision and time, and names clipped to 100 and 48
characters:

| Verdict | When |
| --- | --- |
| `promising` | precision at least 0.5 over at least 5 settled fires |
| `mixed` | between 0.2 and 0.5 |
| `noisy` | under 0.2 |
| `thin` | fewer than 5 settled fires |
| `nothing_to_grade` | no fire has settled |
| `not_gradeable` | a sampling or log-pipeline rule |

When an agent or client asks for promotion, the grade is computed at the ask and stored on the
approval request beside the evidence (`payload.shadowGrade`). It is outside the evidence digest
and the evidence block, so a grade moving never makes an approved digest unmatchable.

## Promotion is a person's decision

`alert_rule.promote` is SENSITIVE and ASKED. For the principal that **authored** the shadow it is
never an ALLOW: not with no policy, not with a policy ALLOW, not under HUMAN_REVIEW, and not under
AUTO at the highest ceiling (no `review_mode.auto_allow` row is written). The registry's
`askFloorWhen: selfAuthored` and the ask floor that holds an unmeasured condition both keep it at
ASK; `preparePromotion` derives `selfAuthored` from the stored author, never from input. Promotion
also needs a day of evidence and no blocking quality key (a resolvable owner, a reachable route, a
rule that is not broken). A shadow that nobody promotes lapses into `EXPIRED` and is archived.

## Tenancy

Every reader takes the organization and the project. A project's list holds its own rules and the
organization-wide alert rules that cover it, never a sibling project's or another organization's. An
issue or deploy that an event names is joined only when it belongs to the same organization, and,
for a project rule, to that rule's own project (an organization-wide rule covers every project).
