1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
//! Frozen structured finding extension contract.
use super::FindingLocation;
/// A structured violation. Every gate, oracle, and verifier produces
/// findings via this common interface. Presence of ANY finding = FAIL.
/// No severity field: at internet scale, all findings are critical.
///
/// Implementations must keep `source()` stable across releases, return a short
/// one-line `message()`, return actionable `fix_hint()` text that begins with
/// `Fix: `, and attach a [`FindingLocation`] whenever the producer can identify
/// a file, line, op id, backend id, or equivalent diagnostic anchor. This is
/// the frozen `ARCHITECTURE.md` §Frozen Contracts finding signature.
pub trait Finding: Send + Sync + std::fmt::Debug {
/// Gate/oracle/source that produced this finding (stable id).
///
/// The source string is part of the frozen contract. Consumers parse it to
/// route findings to the right dashboard or suppression list. Changing a
/// source id is a breaking change for downstream automation.
fn source(&self) -> &'static str;
/// Short, one-line summary.
///
/// This is what appears in CLI output and CI logs. It must fit on one line
/// and contain enough context (op id, file path, or layer name) that a
/// human scanning a thousand-line log can tell what broke without opening
/// a secondary view.
fn message(&self) -> String;
/// Actionable remedy. MUST start with "Fix: ".
///
/// The fix hint is the immune system's whole value proposition. A finding
/// without a fix hint is just noise; a finding with one tells the
/// contributor exactly what change will make the gate pass. Every
/// implementor must treat this as load-bearing output.
fn fix_hint(&self) -> String;
/// Optional source location (file:line, op_id, backend name, etc.).
///
/// Location anchors the finding to a specific place in the codebase so
/// IDE integrations can jump straight to the problem. When a gate cannot
/// pinpoint a location (e.g. a registry-wide aggregate finding), it
/// returns `None` rather than fabricate a fake location.
fn location(&self) -> Option<FindingLocation>;
}