Failure clusters
The failure-signal interface that groups alerts, failed case results, online scores, review findings and incidents into clusters without flooding anyone with tickets.
A failure cluster is where EvalBook collects the signals that something is wrong with the same thing: the same rule firing on the same slice, the same case failing run after run, the same kind of review finding. The improvement component owns clusters and the interface other components use to record a signal. Nothing here is a ticket; a cluster is a deduplicated record of evidence that an investigation or a proposal can be drawn from.
Status (25 October 2026). The improvement component is an empty shell in the application today (one model, no routes, no pages); requirements EV-041 to EV-044, EV-046 and EV-047 are not started in the requirements ledger. This page describes the contract the component is being built to, and nothing on it is available yet.
The interface
The cross-component contract gives the improvement component one function other components may call:
recordFailureSignal(ctx, {
organizationId, projectId,
kind: "case_result" | "online_score" | "review" | "incident" | "alert",
ref, signature, subject, evidenceIds
}) → { cluster_id, created }
ctx is the request or background scope; tenancy is checked against every row. The answer names the cluster the signal joined and whether that cluster was created by this call.
Deduplication
A cluster is identified by tenant, subject and signature. Two signals with the same subject and signature in the same project join one cluster; a repeat adds evidence rather than a cluster. The contract states the purpose plainly: no ticket floods. A rule that fires every fifteen minutes on the same slice, or a case that fails on every run, grows one cluster's evidence rather than producing a new record each time.
What a signal names
kind: where the signal comes from.alertis a fired alert rule;online_scoreis a result of an online scoring policy;case_resultis a case of an evaluation (see reports);reviewis a human finding from a review queue;incidentis a production incident reported through an impact source.ref: the public id of the thing that produced the signal.signature: a digest over what makes two signals the same failure.subject: what failed, with its version and slice where known.evidenceIds: the records a person can open to see the failure.
An item of evidence is a reference, never a copy. The body of a span, a case result or a report stays with the component that owns it and is read under the viewer's own permissions, as the review workspace does.
The first caller: alerts
The one caller written so far is the review component. When an alert event opens, a job records a signal with kind alert, ref the event's public id, a signature over the rule, its deduplication key and the metric, a subject of type alert_rule with the affected version and slice, and the event as the only evidence. Because the improvement component does not yet provide the function, the job records signal_state: unavailable on the event with the code IMPROVEMENT_UNAVAILABLE and is tried again; the alert itself is never blocked. When the function exists, the event shows recorded and the cluster id it joined.
The same fail-closed rule applies to every caller: a function the owning component does not provide yet makes the caller refuse with an explicit code, never succeed by default.
Who may read clusters
Clusters are read with investigation.read, which the trace reader role holds on top of viewer reads, and written through investigations and proposals with investigation.write and proposal.write, which the experiment runner holds. The failure clusters, investigations and proposals entries exist in the project navigation with that capability and are not shown until their pages exist. See roles and access.
What is not in the contract
The contract defines the signal, its deduplication and its answer. It does not yet define how a cluster is triaged, closed or merged, what its own states are, or how clusters are listed; those are the component's to specify when it is built, and this page will say so when they exist. Where a cluster leads is described under investigations and proposals.