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).