Skip to content

Validation Authority and Lifecycle

The validation system is a 9-state finite state machine. Every candidate that enters the pipeline passes through this machine before it can enter the registry — or be formally rejected. State transitions are controlled by validator role authority, ensuring that only qualified reviewers can make binding decisions on each type of knowledge claim.

Validation states

State Meaning Who sets it
PENDING Candidate has been created and is waiting to enter the review queue. No validator has claimed it. System (automatic on candidate creation)
IN_REVIEW A validator has claimed the candidate and is actively reviewing it. Validator (claim action)
APPROVED The validator determined the answer is accurate, complete, and correctly typed. The answer enters the registry as an ApprovedAnswer. Authorized validator
REVISED The validator provided corrected answer text. The revised candidate re-enters the classification pipeline before returning to IN_REVIEW. Authorized validator
REJECTED The candidate is not valid, not accurate, or not appropriate for the registry. It does not enter the registry. The record is retained for audit. Authorized validator
ESCALATED The candidate requires specialist review. It is routed to the escalation queue managed by the governance lead. OPEN_ISSUE candidates always land here. Validator (manual escalation) or System (OPEN_ISSUE rule)
SUPERSEDED An approved answer has been replaced by a newer version. The old version retains this status in the audit history but is no longer returned in active retrieval. System (when a new version is approved)
DISPUTED A contradiction flag or new evidence has called the approved answer's accuracy into question. The answer re-enters the review process. Governance lead or ConflictFlag resolution flow
RETIRED The answer is no longer applicable (product discontinued, policy changed, etc.). It is removed from active retrieval but preserved in the audit history. Governance lead

State transition diagram

stateDiagram-v2
    [*] --> PENDING : Candidate created

    PENDING --> IN_REVIEW : Validator claims

    IN_REVIEW --> APPROVED : Validator approves
    IN_REVIEW --> REVISED : Validator revises
    IN_REVIEW --> REJECTED : Validator rejects
    IN_REVIEW --> ESCALATED : Validator escalates\nor OPEN_ISSUE rule

    REVISED --> IN_REVIEW : Re-classification complete
    REVISED --> APPROVED : Governance lead fast-track\n(configurable)

    ESCALATED --> IN_REVIEW : Specialist returns to queue

    APPROVED --> SUPERSEDED : New version approved
    APPROVED --> DISPUTED : Conflict flag raised
    APPROVED --> RETIRED : Governance lead retires

    DISPUTED --> IN_REVIEW : Re-enters review

Decision meanings and consequences

APPROVED

The candidate passes into the registry as an immutable ApprovedAnswer record. From this point, the answer is available in readouts, retrieval search, and graph analysis. The approving role, the validation record ID, and the approval timestamp are all stored as part of the registry entry.

Approval requires three provenance fields to be present: validation_record_id, owner_role, and evidence_links. If any of these are missing, the system raises a ProvenanceError and blocks registry insertion. This check occurs at write time, not just during review.

REVISED

The validator has found the answer text inaccurate, incomplete, or incorrectly framed, and has provided corrected text. The REVISED decision captures both the validator's correction and the reason for revision.

The revised candidate does not go directly back into the queue as-is. It must re-enter the classification pipeline so that the corrected text receives a fresh Horn type assignment and, for FACTs, a fresh assertion grammar. This ensures that a validator's correction cannot inadvertently create a type mismatch. Once re-classification completes, the candidate returns to IN_REVIEW.

REJECTED

The candidate is determined to be invalid. Common rejection reasons include: the stated claim was inaccurate, the answer was too vague to be useful, the source segment was misidentified, or the candidate duplicates an existing approved answer. Rejected candidates are never entered into the registry. They remain in the candidates table permanently for audit purposes — rejection is not deletion.

ESCALATED

Escalation moves the candidate to a specialist queue outside the normal validator workflow. The governance lead is responsible for triaging escalated items. An escalation may result in the governance lead returning the item to IN_REVIEW (with additional context), sourcing a new candidate to replace it, or formally recording it as an unresolvable gap.

Important: OPEN_ISSUE candidates are automatically escalated by the system. A validator cannot manually approve an OPEN_ISSUE — the application enforces this constraint. When reviewing an OPEN_ISSUE candidate, the only available transitions are ESCALATED and REJECTED.

Post-registry lifecycle states

Once an answer is in the registry, it can still change state. These transitions reflect changes in the world — not errors in the original validation.

SUPERSEDED

When new information makes a registry answer obsolete, a new candidate is created, validated, and approved. On approval of the new version, the system automatically sets the previous version's status to SUPERSEDED and records the supersedes_id link. Both versions remain in the database. The version chain is traversable via the graph API.

DISPUTED

A DISPUTED answer is one where a contradiction flag has been raised, or where new evidence calls the answer's accuracy into question. Disputed answers are flagged in readouts and retrieval results — consumers are alerted that the answer is under review. The answer re-enters the validation queue at IN_REVIEW for re-assessment.

RETIRED

Retirement is a deliberate governance action by the knowledge architect or governance lead. An answer is retired when it is no longer applicable — not because it was wrong when approved, but because the world has changed in a way that makes the answer irrelevant or potentially misleading. Retired answers are excluded from active retrieval but are preserved in the audit history.

Conflict flags and validation blocking

During validation, the system checks whether the candidate's assertion grammar conflicts with any existing approved answer. A ConflictFlag is raised when two answers share the same subject, predicate, and scope but assert different object values.

By default, a raised ConflictFlag blocks the APPROVED decision — the validator is shown the conflicting record and must resolve the conflict before approval can proceed. Resolution options are:

  1. Reject the new candidate — the existing answer is correct.
  2. Supersede the existing answer — the new candidate is correct; the old one is outdated.
  3. Escalate — the conflict is too complex for the current validator; governance lead must decide.

This blocking behavior is configurable per deployment. Organizations with high ingestion volume may configure ConflictFlags to warn rather than block, with governance lead review deferred to a scheduled quality pass.

Authority constraints summary

Decision Who can make it
Claim (IN_REVIEW) Any validator with queue access
APPROVED Authorized validator for the candidate's Horn type (per KGS authority table)
REVISED Authorized validator for the candidate's Horn type
REJECTED Any validator
ESCALATED Any validator; system (for OPEN_ISSUE)
RETIRED Knowledge Architect / Governance Lead only
DISPUTED (set) Knowledge Architect / Governance Lead, or automatic ConflictFlag

Note: Platform admins do not participate in the validation state machine. They have no approval authority by design — separation of duties between the platform layer and the governance layer is a core Raw to Knowledge principle.