Skip to content
bucker

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