Initial whetstone_RSA architecture and C++ scaffold

include/whetstone_rsa/diagnosis_engine.h

@@ -0,0 +1,25 @@
+#pragma once
+
+#include "whetstone_rsa/probe_registry.h"
+
+namespace whetstone::rsa {
+
+class DiagnosisEngine {
+public:
+    explicit DiagnosisEngine(ProbeRegistry probe_registry);
+
+    [[nodiscard]] GateDiagnosis diagnose(const GateDefinition& gate_definition,
+                                         const GateEvidence& evidence,
+                                         const PolicyContext& policy_context) const;
+
+private:
+    [[nodiscard]] static PolicyRecommendation recommend_policy(const GateDefinition& gate_definition,
+                                                               const GateEvidence& evidence,
+                                                               const PolicyContext& policy_context,
+                                                               FailureClass primary_failure_class,
+                                                               const std::vector<Intervention>& interventions);
+
+    ProbeRegistry probe_registry_;
+};
+
+}  // namespace whetstone::rsa

include/whetstone_rsa/probe.h

@@ -0,0 +1,22 @@
+#pragma once
+
+#include "whetstone_rsa/types.h"
+
+#include <memory>
+#include <string>
+
+namespace whetstone::rsa {
+
+class Probe {
+public:
+    virtual ~Probe() = default;
+
+    [[nodiscard]] virtual std::string id() const = 0;
+    [[nodiscard]] virtual bool supports(const GateDefinition& gate_definition,
+                                        const GateEvidence& evidence) const = 0;
+    [[nodiscard]] virtual ProbeResult run(const ProbeRequest& request) const = 0;
+};
+
+using ProbePtr = std::shared_ptr<Probe>;
+
+}  // namespace whetstone::rsa

include/whetstone_rsa/probe_registry.h

@@ -0,0 +1,22 @@
+#pragma once
+
+#include "whetstone_rsa/probe.h"
+
+#include <unordered_map>
+#include <vector>
+
+namespace whetstone::rsa {
+
+class ProbeRegistry {
+public:
+    void register_probe(ProbePtr probe);
+    [[nodiscard]] ProbePtr find(const std::string& probe_id) const;
+    [[nodiscard]] std::vector<ProbePtr> applicable_probes(const GateDefinition& gate_definition,
+                                                          const GateEvidence& evidence) const;
+    [[nodiscard]] std::vector<std::string> ids() const;
+
+private:
+    std::unordered_map<std::string, ProbePtr> probes_;
+};
+
+}  // namespace whetstone::rsa

include/whetstone_rsa/probes/confidence_threshold_probe.h

@@ -0,0 +1,15 @@
+#pragma once
+
+#include "whetstone_rsa/probe.h"
+
+namespace whetstone::rsa {
+
+class ConfidenceThresholdProbe final : public Probe {
+public:
+    [[nodiscard]] std::string id() const override;
+    [[nodiscard]] bool supports(const GateDefinition& gate_definition,
+                                const GateEvidence& evidence) const override;
+    [[nodiscard]] ProbeResult run(const ProbeRequest& request) const override;
+};
+
+}  // namespace whetstone::rsa

include/whetstone_rsa/suitability_assessor.h

@@ -0,0 +1,12 @@
+#pragma once
+
+#include "whetstone_rsa/types.h"
+
+namespace whetstone::rsa {
+
+class SuitabilityAssessor {
+public:
+    [[nodiscard]] GateSuitability assess(const GateDefinition& gate_definition) const;
+};
+
+}  // namespace whetstone::rsa

include/whetstone_rsa/types.h

@@ -0,0 +1,192 @@
+#pragma once
+
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+namespace whetstone::rsa {
+
+enum class RiskTier {
+    Low,
+    Medium,
+    High,
+};
+
+enum class InputStructure {
+    Structured,
+    Unstructured,
+    Hybrid,
+};
+
+enum class InputModality {
+    Textual,
+    Numeric,
+    Symbolic,
+    Multimodal,
+};
+
+enum class OutputTopology {
+    Discrete,
+    Continuous,
+    Hybrid,
+};
+
+enum class OutputConstraint {
+    Deterministic,
+    Bounded,
+    Open,
+};
+
+enum class LabelStability {
+    Stable,
+    Mixed,
+    NonStationary,
+};
+
+enum class FailureClass {
+    Unknown,
+    CapacityLimitedGate,
+    FactorizableGate,
+    NonStationaryGate,
+    MissingContextGate,
+    DeterministicDisguisedAsMlGate,
+    LabelSpaceMismatch,
+    GuardrailLimitedGate,
+};
+
+enum class Intervention {
+    CollectMoreEvidence,
+    KeepCurrentGate,
+    DeployWithGuardrails,
+    RaiseConfidenceThreshold,
+    AddRetryWithContext,
+    AddDeterministicPrepass,
+    ReplaceWithDeterministicLogic,
+    FactorIntoSubgates,
+    SwitchToHierarchicalGate,
+    ReviseLabelSchema,
+    EnrichInputContext,
+    EvaluateLargerModelTier,
+};
+
+enum class DeployMode {
+    AutoAccept,
+    GuardedAccept,
+    AbstainFirst,
+    ResearchOnly,
+};
+
+enum class TargetLayer {
+    Deterministic,
+    Rsa,
+    Slm,
+    Llm,
+    Human,
+};
+
+struct PolicyRecommendation {
+    DeployMode deploy_mode = DeployMode::ResearchOnly;
+    std::optional<double> threshold_hint;
+    bool abstain_required = false;
+    std::string retry_strategy;
+    std::vector<std::string> escalation_targets;
+};
+
+struct GateDefinition {
+    std::string gate_id;
+    std::string task_family;
+    std::vector<std::string> labels;
+    InputStructure input_structure = InputStructure::Structured;
+    InputModality input_modality = InputModality::Symbolic;
+    OutputTopology output_topology = OutputTopology::Discrete;
+    OutputConstraint output_constraint = OutputConstraint::Bounded;
+    RiskTier risk_tier = RiskTier::Medium;
+    LabelStability label_stability = LabelStability::Stable;
+    bool deterministic_baseline_available = false;
+    bool supports_abstain = true;
+    std::vector<std::vector<std::string>> candidate_factorizations;
+    std::unordered_map<std::string, std::string> metadata;
+};
+
+struct ConfusionItem {
+    std::string actual;
+    std::string predicted;
+    int count = 0;
+};
+
+struct GateEvidence {
+    std::string gate_id;
+    std::string model_tier;
+    std::optional<double> raw_accuracy;
+    std::optional<double> accept_rate;
+    std::optional<double> accuracy_on_accepted;
+    std::optional<double> abstain_rate;
+    std::optional<double> retry_recovery_rate;
+    std::optional<double> escalation_rate;
+    std::optional<double> silent_error_rate;
+    std::optional<double> expected_calibration_error;
+    std::optional<double> latency_ms;
+    std::optional<double> compute_cost;
+    std::vector<ConfusionItem> confusion_summary;
+    std::vector<std::string> notes;
+};
+
+struct PolicyContext {
+    double max_silent_error_rate = 0.10;
+    double min_accuracy_on_accepted = 0.90;
+    double max_latency_ms = 100.0;
+    bool deterministic_checks_exist = false;
+    std::vector<std::string> available_escalation_targets;
+};
+
+struct ProbeRequest {
+    const GateDefinition& gate_definition;
+    const GateEvidence& evidence;
+    const PolicyContext& policy_context;
+};
+
+struct ProbeResult {
+    std::string probe_id;
+    std::string status = "success";
+    std::unordered_map<std::string, double> signals;
+    std::vector<Intervention> recommendation_hints;
+    std::vector<FailureClass> failure_hints;
+    double confidence = 0.0;
+};
+
+struct GateDiagnosis {
+    std::string gate_id;
+    FailureClass primary_failure_class = FailureClass::Unknown;
+    std::vector<FailureClass> secondary_failure_classes;
+    std::vector<std::string> supporting_signals;
+    std::vector<std::string> recommended_probes;
+    std::vector<Intervention> recommended_interventions;
+    PolicyRecommendation recommended_policy;
+    double confidence = 0.0;
+};
+
+struct GateSuitability {
+    std::string gate_id;
+    bool recommended = false;
+    TargetLayer target_layer = TargetLayer::Human;
+    std::string rationale;
+    double bounded_output_confidence = 0.0;
+    bool deterministic_baseline_available = false;
+    LabelStability label_stability_risk = LabelStability::Stable;
+    std::string suggested_gate_shape;
+};
+
+std::string to_string(RiskTier tier);
+std::string to_string(InputStructure input_structure);
+std::string to_string(InputModality input_modality);
+std::string to_string(OutputTopology output_topology);
+std::string to_string(OutputConstraint output_constraint);
+std::string to_string(LabelStability stability);
+std::string to_string(FailureClass failure_class);
+std::string to_string(Intervention intervention);
+std::string to_string(DeployMode deploy_mode);
+std::string to_string(TargetLayer target_layer);
+
+}  // namespace whetstone::rsa