constitutional_validator.cpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
#include <entropic/core/constitutional_validator.h>
#include <entropic/core/hook_registry.h>
 
#include <entropic/types/logging.h>
 
#include <cstdlib>
#include <cstring>
 
namespace entropic {
 
namespace {
auto logger = entropic::log::get("core.constitutional_validator");
} // anonymous namespace
 
// Forward declarations for static helpers used in validate()
static std::string strip_think_blocks(const std::string& content);
static bool is_pure_tool_call(const std::string& content);
 
ConstitutionalValidator::ConstitutionalValidator(
    const ConstitutionalValidationConfig& config,
    const std::string& constitution_text)
    : config_(config),
      constitution_text_(constitution_text),
      global_enabled_(config.enabled) {
    context_.validator = this;
    context_.inference = nullptr;
}
 
entropic_error_t ConstitutionalValidator::attach(
    HookInterface* hook_iface,
    InferenceInterface* inference) {
    inference_ = inference;
    context_.inference = inference;
 
    if (hook_iface == nullptr || hook_iface->registry == nullptr) {
        return ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
 
    auto* reg = static_cast<HookRegistry*>(hook_iface->registry);
    return reg->register_hook(
        ENTROPIC_HOOK_POST_GENERATE,
        hook_callback,
        &context_,
        config_.priority);
}
 
void ConstitutionalValidator::detach(HookInterface* hook_iface) {
    if (hook_iface == nullptr || hook_iface->registry == nullptr) {
        return;
    }
    auto* reg = static_cast<HookRegistry*>(hook_iface->registry);
    reg->deregister_hook(
        ENTROPIC_HOOK_POST_GENERATE, hook_callback, &context_);
}
 
bool ConstitutionalValidator::should_validate(
    const std::string& identity_name) const {
    std::lock_guard<std::mutex> lock(overrides_mutex_);
    auto it = identity_overrides_.find(identity_name);
    if (it != identity_overrides_.end()) {
        return it->second;
    }
    // Default skip for tiers that stream before the hook fires
    for (const auto& skip : config_.skip_tiers) {
        if (skip == identity_name) { return false; }
    }
    return global_enabled_;
}
 
void ConstitutionalValidator::set_global_enabled(bool enabled) {
    std::lock_guard<std::mutex> lock(overrides_mutex_);
    global_enabled_ = enabled;
}
 
// ── gh#30 (v2.1.5): consumer-driven retry controls ───────
 
void ConstitutionalValidator::set_auto_retry(bool enabled) {
    auto_retry_enabled_.store(enabled);
}
 
bool ConstitutionalValidator::auto_retry_enabled() const {
    return auto_retry_enabled_.load();
}
 
entropic_error_t ConstitutionalValidator::resume_retry() {
    std::optional<PendingValidationState> state;
    {
        std::lock_guard lock(pending_mutex_);
        state = std::move(pending_state_);
        pending_state_.reset();
    }
    if (!state) {
        return ENTROPIC_ERROR_INVALID_STATE;
    }
    auto result = apply_revisions(
        state->result, state->critique,
        state->messages_json.empty() ? nullptr
                                     : state->messages_json.c_str());
    store_result(result);
    logger->info("Constitutional validation resumed (gh#30): "
                 "final verdict={}", static_cast<int>(result.verdict));
    return ENTROPIC_OK;
}
 
entropic_error_t ConstitutionalValidator::accept_last() {
    std::optional<PendingValidationState> state;
    {
        std::lock_guard lock(pending_mutex_);
        state = std::move(pending_state_);
        pending_state_.reset();
    }
    if (!state) {
        return ENTROPIC_ERROR_INVALID_STATE;
    }
    ValidationResult result = std::move(state->result);
    result.verdict = ValidationVerdict::passed_consumer_override;
    store_result(result);
    logger->info("Constitutional validation accepted by consumer "
                 "(gh#30): attempt_n={}", result.attempt_n);
    return ENTROPIC_OK;
}
 
void ConstitutionalValidator::set_attempt_boundary_cb(
    void (*cb)(int, void*), void* user_data) {
    std::lock_guard<std::mutex> lock(attempt_boundary_mutex_);
    attempt_boundary_.cb = cb;
    attempt_boundary_.user_data = user_data;
}
 
void ConstitutionalValidator::set_critique_callbacks(
    void (*start_cb)(void*),
    void (*end_cb)(void*),
    void* user_data) {
    std::lock_guard<std::mutex> lock(critique_cbs_mutex_);
    critique_cbs_.start_cb = start_cb;
    critique_cbs_.end_cb = end_cb;
    critique_cbs_.user_data = user_data;
}
 
void ConstitutionalValidator::set_identity_validation(
    const std::string& identity_name, bool enabled) {
    std::lock_guard<std::mutex> lock(overrides_mutex_);
    identity_overrides_[identity_name] = enabled;
}
 
void ConstitutionalValidator::set_tier_rules(
    const std::string& identity_name,
    const std::vector<std::string>& rules) {
    std::lock_guard<std::mutex> lock(overrides_mutex_);
    tier_rules_[identity_name] = rules;
}
 
ValidationResult ConstitutionalValidator::validate(
    const std::string& content,
    const std::string& tier,
    const char* messages_json) {
    ValidationResult result;
    result.content = content;
 
    if (!should_validate(tier)) {
        logger->info("Validation skipped for tier '{}'", tier);
        result.verdict = ValidationVerdict::skipped;
        store_result(result);
        return result;
    }
 
    // Strip think blocks and skip pure tool-call outputs
    auto cleaned = strip_think_blocks(content);
    if (cleaned.empty() || is_pure_tool_call(cleaned)) {
        logger->info("Validation skipped: pure tool-call or empty");
        result.verdict = ValidationVerdict::skipped;
        store_result(result);
        return result;
    }
 
    current_tier_ = tier;
    logger->info("Validation start: {} chars, tier='{}'",
                 cleaned.size(), tier);
    result = run_validation_loop(cleaned, tier, messages_json);
    log_verdict(result);
    store_result(result);
    return result;
}
 
void ConstitutionalValidator::log_verdict(
    const ValidationResult& result) const {
    switch (result.verdict) {
    case ValidationVerdict::passed:
        logger->info("Validation passed (no violations)");
        break;
    case ValidationVerdict::revised:
        logger->info("Validation revised ({} revision(s) applied)",
                     result.revision_count);
        break;
    case ValidationVerdict::rejected_reverted_length:
        logger->warn("Validation reverted "
                     "({} violation(s) found; revision discarded for length)",
                     result.final_critique.violations.size());
        break;
    case ValidationVerdict::rejected_max_revisions:
        logger->warn("Validation rejected "
                     "(max revisions exhausted; {} violation(s) remain)",
                     result.final_critique.violations.size());
        break;
    case ValidationVerdict::skipped:
        // log-site above already emits "Validation skipped…"
        break;
    case ValidationVerdict::paused_pending_consumer:
        logger->info("Validation paused (gh#30): "
                     "{} violation(s); awaiting consumer",
                     result.final_critique.violations.size());
        break;
    case ValidationVerdict::passed_consumer_override:
        logger->info("Validation accepted by consumer (gh#30): "
                     "attempt_n={}", result.attempt_n);
        break;
    }
}
 
ValidationResult ConstitutionalValidator::last_result() const {
    std::lock_guard<std::mutex> lock(result_mutex_);
    return last_result_;
}
 
// ── Hook Callback ────────────────────────────────────────
 
int ConstitutionalValidator::hook_callback(
    entropic_hook_point_t /*hook_point*/,
    const char* context_json,
    char** modified_json,
    void* user_data) {
    *modified_json = nullptr;
    auto* ctx = static_cast<ValidationContext*>(user_data);
    if (ctx == nullptr || ctx->validator == nullptr) {
        return 0;
    }
 
    return ctx->validator->handle_hook(context_json, modified_json);
}
 
// ── Critique Prompt Assembly ──────────────────────────────
 
std::string ConstitutionalValidator::build_critique_prompt(
    const std::string& content) const {
    std::string prompt;
    prompt.reserve(constitution_text_.size() + content.size() + 512);
 
    prompt += "You are a compliance evaluator. "
              "Respond ONLY with the structured JSON evaluation.\n\n";
 
    // When per-tier rules exist: they are the primary rubric,
    // constitution is background context. When absent: constitution
    // is the sole rubric.
    bool has_tier_rules = false;
    {
        std::lock_guard<std::mutex> lock(overrides_mutex_);
        auto it = tier_rules_.find(current_tier_);
        has_tier_rules = (it != tier_rules_.end()
                          && !it->second.empty());
        if (has_tier_rules) {
            prompt += "Evaluate against these rules for the '"
                   + current_tier_ + "' identity:\n";
            for (const auto& rule : it->second) {
                prompt += "- " + rule + "\n";
            }
            prompt += "\nBackground constitutional guidance:\n";
            prompt += constitution_text_;
        } else {
            prompt += "Constitutional Rules:\n";
            prompt += constitution_text_;
        }
    }
 
    // Provide tool call manifest so validator can assess grounding
    if (!current_tool_context_.empty()) {
        prompt += "\n\nTool calls made this turn:\n";
        prompt += current_tool_context_;
    }
 
    // Issue #5 (v2.1.3): un-pruned tool-result content. Lets the
    // critique pass verify file:line citations against actual
    // evidence rather than the manifest-plus-stubs that pre-2.1.3
    // produced. Engine surfaces this when the messages have been
    // partially pruned (#6 limits when this happens, but legitimate
    // long-context delegations still trigger it).
    if (!current_tool_evidence_.empty()) {
        prompt += "\n\nTool result evidence (verify citations against this):\n";
        prompt += current_tool_evidence_;
    }
 
    prompt += "\n\nEvaluate this output for compliance:\n\n---\n";
    prompt += content;
    prompt += "\n---";
    return prompt;
}
 
CritiqueResult ConstitutionalValidator::parse_critique(
    const std::string& json_str) {
    CritiqueResult result;
    result.raw_json = json_str;
 
    if (!extract_compliant_field(json_str, result)) {
        // Fail-open: if the model produced JSON we can't parse (e.g.,
        // "constitutional_compliance_status" instead of "compliant"),
        // treat it as compliant rather than triggering a revision loop
        // on a parse error. The grammar constraint is the real fix;
        // this is the safety net when grammar loading fails.
        result.compliant = true;
        return result;
    }
 
    extract_violations(json_str, result);
    extract_revised_field(json_str, result);
    return result;
}
 
// ── Private Implementation ────────────────────────────────
 
void ConstitutionalValidator::store_result(
    const ValidationResult& result) {
    std::lock_guard<std::mutex> lock(result_mutex_);
    last_result_ = result;
}
 
ValidationResult ConstitutionalValidator::run_validation_loop(
    const std::string& content,
    const std::string& tier,
    const char* messages_json) {
    ValidationResult result;
    result.content = content;
 
    auto critique = run_critique(content);
    result.final_critique = critique;
 
    if (critique.compliant) {
        return result;
    }
 
    // gh#30 (v2.1.5): when the consumer has disabled auto-retry, stop
    // here and stash enough state for resume_retry()/accept_last() to
    // continue.
    if (!auto_retry_enabled_.load()) {
        result.verdict = ValidationVerdict::paused_pending_consumer;
        result.attempt_n = 0;
        {
            std::lock_guard lock(pending_mutex_);
            pending_state_ = PendingValidationState{
                result, critique,
                messages_json ? std::string(messages_json) : std::string{},
                tier};
        }
        logger->info("Constitutional validation paused (gh#30): "
                     "auto_retry disabled, awaiting consumer decision");
        return result;
    }
 
    return apply_revisions(result, critique, messages_json);
}
 
ValidationResult ConstitutionalValidator::apply_revisions(
    ValidationResult result,
    const CritiqueResult& initial_critique,
    const char* messages_json) {
    auto critique = initial_critique;
    for (int i = 0; i < config_.max_revisions; ++i) {
        const auto& before = result.content;
        // gh#30 (v2.1.5): fire attempt-boundary callback before the
        // revision so consumers can split rendered output cleanly.
        // Snapshot under the mutex first so a concurrent
        // set_attempt_boundary_cb() cannot tear the {cb, user_data}
        // pair mid-call (post-2.1.5 verification hardening).
        AttemptBoundaryCb cb_snap;
        {
            std::lock_guard<std::mutex> lk(attempt_boundary_mutex_);
            cb_snap = attempt_boundary_;
        }
        if (cb_snap.cb != nullptr) {
            try {
                cb_snap.cb(i + 1, cb_snap.user_data);
            } catch (...) {
                logger->warn("attempt_boundary_cb threw; swallowed at "
                             ".so boundary (gh#30)");
            }
        }
        auto revised = attempt_revision(before, critique, messages_json);
 
        // Length safety valve: reject revisions that gut the content
        if (revised.size() < before.size() / 2) {
            logger->warn("Constitutional validation: revision {}/{} "
                         "shrank content {}→{} chars (>50%); "
                         "discarding revision, returning original",
                         i + 1, config_.max_revisions,
                         before.size(), revised.size());
            result.verdict =
                ValidationVerdict::rejected_reverted_length;
            result.attempt_n = i + 1;
            return result;
        }
 
        result.content = revised;
        result.was_revised = true;
        result.revision_count = i + 1;
        result.attempt_n = i + 1;
 
        critique = run_critique(revised);
        result.final_critique = critique;
 
        if (critique.compliant) { break; }
    }
 
    if (!critique.compliant) {
        logger->warn("Constitutional validation: max revisions ({}) "
                     "exhausted, returning last output",
                     config_.max_revisions);
        result.verdict = ValidationVerdict::rejected_max_revisions;
    } else if (result.was_revised) {
        result.verdict = ValidationVerdict::revised;
    }
    return result;
}
 
std::string ConstitutionalValidator::attempt_revision(
    const std::string& content,
    const CritiqueResult& critique,
    const char* messages_json) {
    if (!critique.revised.empty()) {
        return critique.revised;
    }
    return revise(content, critique, messages_json);
}
 
CritiqueResult ConstitutionalValidator::run_critique(
    const std::string& content) {
    if (inference_ == nullptr || inference_->generate == nullptr) {
        logger->warn("Constitutional validation: no inference "
                     "interface, skipping critique");
        return {};
    }
 
    auto messages = build_critique_messages(content);
    auto params = build_critique_params();
    char* result_json = nullptr;
 
    // gh#50 (v2.1.12): snapshot the callback pair under the mutex
    // so a consumer reassigning the slot mid-critique cannot tear
    // {start_cb, end_cb, user_data}. Invoke OUTSIDE the lock so a
    // pathological consumer-side handler that re-enters
    // set_critique_callbacks doesn't self-deadlock.
    CritiqueCallbacks cbs;
    {
        std::lock_guard<std::mutex> lock(critique_cbs_mutex_);
        cbs = critique_cbs_;
    }
    if (cbs.start_cb != nullptr) { cbs.start_cb(cbs.user_data); }
 
    int rc = inference_->generate(
        messages.c_str(), params.c_str(),
        &result_json, inference_->backend_data);
 
    if (cbs.end_cb != nullptr) { cbs.end_cb(cbs.user_data); }
 
    if (rc != 0 || result_json == nullptr) {
        logger->warn("Constitutional validation: critique generation "
                     "failed (rc={})", rc);
        return {};
    }
 
    std::string raw(result_json);
    if (inference_->free_fn != nullptr) {
        inference_->free_fn(result_json);
    }
 
    return parse_critique(raw);
}
 
std::string ConstitutionalValidator::build_critique_messages(
    const std::string& content) const {
    auto prompt = build_critique_prompt(content);
    return build_single_turn_json(prompt);
}
 
std::string ConstitutionalValidator::build_critique_params() const {
    std::string params = "{\"grammar_key\":\"";
    params += config_.grammar_key;
    params += "\",\"max_tokens\":";
    params += std::to_string(config_.max_critique_tokens);
    params += ",\"temperature\":";
    params += std::to_string(config_.temperature);
    params += ",\"enable_thinking\":";
    params += config_.enable_thinking ? "true" : "false";
    // E4 (2.0.6-rc17): route critique on a dedicated (typically
    // smaller) tier so grammar-constrained sampling doesn't burn
    // 35B primary inference. Empty -> default_tier selected by
    // the inference interface.
    if (!config_.critique_tier.empty()) {
        params += ",\"tier\":\"";
        params += config_.critique_tier;
        params += "\"";
    }
    params += "}";
    return params;
}
 
std::string ConstitutionalValidator::revise(
    const std::string& original,
    const CritiqueResult& critique,
    const char* messages_json) {
    if (inference_ == nullptr || inference_->generate == nullptr) {
        return original;
    }
 
    auto augmented = build_revision_messages(
        original, critique, messages_json);
    char* result_json = nullptr;
 
    // Unconstrained generation: revision output is free-form prose,
    // not the structured JSON schema used for the critique pass.
    int rc = inference_->generate(
        augmented.c_str(), "{}", &result_json,
        inference_->backend_data);
 
    if (rc != 0 || result_json == nullptr) {
        logger->warn("Constitutional validation: revision generation "
                     "failed (rc={})", rc);
        return original;
    }
 
    std::string revised(result_json);
    if (inference_->free_fn != nullptr) {
        inference_->free_fn(result_json);
    }
    return revised;
}
 
// ── JSON String Helpers ──────────────────────────────────
// Manual JSON construction avoids nlohmann/json dependency in core.so.
 
static std::string json_escape(const std::string& s) {
    std::string out;
    out.reserve(s.size() + 16);
    for (char c : s) {
        switch (c) {
            case '"':  out += "\\\""; break;
            case '\\': out += "\\\\"; break;
            case '\n': out += "\\n"; break;
            case '\r': out += "\\r"; break;
            case '\t': out += "\\t"; break;
            default:   out += c; break;
        }
    }
    return out;
}
 
std::string ConstitutionalValidator::build_single_turn_json(
    const std::string& prompt) const {
    std::string json = "[{\"role\":\"user\",\"content\":\"";
    json += json_escape(prompt);
    json += "\"}]";
    return json;
}
 
std::string ConstitutionalValidator::build_revision_messages(
    const std::string& original,
    const CritiqueResult& critique,
    const char* messages_json) const {
    std::string feedback = build_feedback_text(critique);
    return inject_feedback_into_messages(
        original, feedback, messages_json);
}
 
std::string ConstitutionalValidator::build_feedback_text(
    const CritiqueResult& critique) const {
    std::string feedback =
        "Your response violated these constitutional rules:\\n";
    for (const auto& v : critique.violations) {
        feedback += "- " + v.rule + ": " + v.explanation + "\\n";
    }
    feedback += "Please revise your response to comply with all "
                "constitutional rules.";
    return feedback;
}
 
std::string ConstitutionalValidator::inject_feedback_into_messages(
    const std::string& original,
    const std::string& feedback,
    const char* messages_json) const {
    std::string base;
    if (messages_json != nullptr) {
        base = std::string(messages_json);
    } else {
        // Prefer identity system prompt over bare constitution — keeps
        // the model in persona during revision (prevents apology spirals).
        const auto& sys = !current_system_prompt_.empty()
            ? current_system_prompt_ : constitution_text_;
        base = "[{\"role\":\"system\",\"content\":\""
             + json_escape(sys) + "\"}";
    }
 
    // Strip trailing ]
    if (!base.empty() && base.back() == ']') {
        base.pop_back();
    }
 
    // Add comma if there were existing messages
    if (base.size() > 1) {
        base += ",";
    }
 
    base += "{\"role\":\"assistant\",\"content\":\"";
    base += json_escape(original);
    base += "\"},{\"role\":\"system\",\"content\":\"";
    base += json_escape("[CONSTITUTIONAL REVIEW] " + feedback);
    base += "\"}]";
    return base;
}
 
static std::string strip_think_blocks(const std::string& content) {
    std::string result;
    size_t pos = 0;
    while (pos < content.size()) {
        auto open = content.find("<think>", pos);
        if (open == std::string::npos) {
            result.append(content, pos);
            break;
        }
        result.append(content, pos, open - pos);
        auto close = content.find("</think>", open);
        pos = (close == std::string::npos)
            ? content.size()
            : close + 8;
    }
    return result;
}
 
static bool is_pure_tool_call(const std::string& content) {
    std::string stripped = content;
    // Remove all <tool_call>...</tool_call> blocks
    while (true) {
        auto open = stripped.find("<tool_call>");
        if (open == std::string::npos) { break; }
        auto close = stripped.find("</tool_call>", open);
        if (close == std::string::npos) { break; }
        stripped.erase(open, close + 12 - open);
    }
    // If only whitespace remains, it was a pure tool call
    return stripped.find_first_not_of(" \t\n\r") == std::string::npos;
}
 
int ConstitutionalValidator::handle_hook(
    const char* context_json,
    char** modified_json) {
    *modified_json = nullptr;
 
    auto content = extract_json_string(context_json, "content");
    auto tier = extract_json_string(context_json, "tier");
 
    if (content.empty()) { return 0; }
 
    // Store per-call context for build_critique_prompt and revision
    current_tool_context_ = extract_json_string(
        context_json, "tool_context");
    // Issue #5 (v2.1.3): un-pruned tool-result content surfaced by the
    // engine so the validator can verify citations against actual
    // evidence rather than post-prune stubs. Optional field — pre-2.1.3
    // engines that don't send it give an empty string, falling back to
    // the manifest-only behaviour.
    current_tool_evidence_ = extract_json_string(
        context_json, "tool_evidence");
    current_system_prompt_ = extract_json_string(
        context_json, "system_prompt");
 
    auto result = validate(content, tier, nullptr);
    if (!result.was_revised) {
        return 0;
    }
 
    write_modified_json(result.content, modified_json);
    return 0;
}
 
void ConstitutionalValidator::write_modified_json(
    const std::string& content,
    char** modified_json) {
    std::string out = "{\"content\":\"";
    out += json_escape(content);
    out += "\"}";
 
    auto* buf = static_cast<char*>(malloc(out.size() + 1));
    if (buf != nullptr) {
        std::memcpy(buf, out.c_str(), out.size() + 1);
        *modified_json = buf;
    }
}
 
// ── Minimal JSON Field Extraction ─────────────────────────
// No nlohmann/json in core.so. These extract known fields from
// simple flat JSON objects by string search.
 
std::string ConstitutionalValidator::extract_json_string(
    const char* json, const char* key) {
    if (json == nullptr || key == nullptr) {
        return {};
    }
 
    std::string needle = std::string("\"") + key + "\"";
    const char* pos = strstr(json, needle.c_str());
    if (pos == nullptr) {
        return {};
    }
 
    return extract_string_after_colon(pos + needle.size());
}
 
std::string ConstitutionalValidator::extract_string_after_colon(
    const char* pos) {
    // Skip whitespace and colon
    while (*pos == ' ' || *pos == ':' || *pos == '\t') {
        ++pos;
    }
    if (*pos != '"') {
        return {};
    }
    ++pos; // skip opening quote
 
    std::string value;
    while (*pos != '\0' && *pos != '"') {
        if (*pos == '\\' && *(pos + 1) != '\0') {
            ++pos;
            switch (*pos) {
                case 'n': value += '\n'; break;
                case 't': value += '\t'; break;
                case 'r': value += '\r'; break;
                default:  value += *pos; break;
            }
        } else {
            value += *pos;
        }
        ++pos;
    }
    return value;
}
 
bool ConstitutionalValidator::extract_compliant_field(
    const std::string& json, CritiqueResult& result) {
    auto pos = json.find("\"compliant\"");
    if (pos == std::string::npos) {
        logger->warn("Constitutional validation: malformed critique "
                     "JSON — missing 'compliant' field");
        return false;
    }
 
    result.compliant = (json.find("true", pos) < json.find("false", pos));
    return true;
}
 
void ConstitutionalValidator::extract_violations(
    const std::string& json, CritiqueResult& result) {
    size_t search_pos = 0;
 
    while (true) {
        auto v = extract_next_violation(json, search_pos);
        if (!v.has_value()) {
            break;
        }
        result.violations.push_back(std::move(v.value()));
    }
}
 
std::optional<Violation>
ConstitutionalValidator::extract_next_violation(
    const std::string& json, size_t& pos) {
    auto rule_pos = json.find("\"rule\"", pos);
    if (rule_pos == std::string::npos) {
        return std::nullopt;
    }
 
    Violation v;
    v.rule = extract_json_string(
        json.c_str() + rule_pos, "rule");
    v.excerpt = extract_json_string(
        json.c_str() + rule_pos, "excerpt");
    v.explanation = extract_json_string(
        json.c_str() + rule_pos, "explanation");
 
    pos = rule_pos + 1;
    return v;
}
 
void ConstitutionalValidator::extract_revised_field(
    const std::string& json, CritiqueResult& result) {
    result.revised = extract_json_string(json.c_str(), "revised");
}
 
} // namespace entropic