promote_candidate

Category: intel
Access: write
Audience: advanced (ordinary users do not normally call this directly)

Purpose

Governance gate promoting one candidate claim to a canonical fact. Call it with human_confirmed after review; sensitive scopes accept no other mode.

Arguments

Required: claim_id.

Optional: mode.

claim_id.
mode. Note: Defaults human_confirmed. multi_evidence and imported are policy-gated; auto_layer1 is pipeline-internal.

Result

Object with claim_id, promoted flag, reason when false, and on success fact_id, subject, predicate, object, scope, validation_mode, and reused_existing_fact when deduplicated.

Boundaries

Operates inside the selected profile boundary. Sensitive scopes (mapping, validation, bridge, export) accept only human_confirmed; multi_evidence additionally needs memory scope, three evidence entries, and confidence at least 0.7.

Lifecycle / side effects

Marks the claim promoted, creates the canonical fact (or reinforces an identical live fact, reporting reused_existing_fact), copies evidence into provenance, links contradictions with counts refreshed, and records history plus a run-history entry. Idempotent via the promoted claim status.

Errors

Unknown claim returns not-found. Non-candidate status and invalid modes return normal error payloads. Blocked promotions (human confirmation needed, insufficient evidence, low confidence, wrong scope) return promoted false with a reason, not an error.

Example

{
  "claim_id": "<uuid>",
  "mode": "human_confirmed"
}

Result shape:

{
  "claim_id": "<uuid>",
  "fact_id": "<uuid>",
  "promoted": true,
  "scope": "memory",
  "validation_mode": "human_confirmed"
}