Knowledge Graph Provenance and Two-Tier Trust Model

Every node (kg_nodes) and edge (kg_edges) in the Wikantik Knowledge Graph carries two orthogonal trust dimensions:

1. provenance (added in migration V004): How the entity or relationship originally entered the database (human-authored, human-curated, ai-inferred, or ai-reviewed).
2. tier (added in migration V024): How far the row has been vetted along the review ladder (machine vs. human).

Separating origin (provenance) from verification state (tier) prevents a classic failure mode of single-column trust models: when an administrator approves an LLM-extracted edge, the system needs to know both that the fact is now human-vetted (tier = 'human') and that it originally came from the extraction pipeline (provenance = 'ai-inferred') for precision/recall auditing.

1. State Machine: Provenance & Tier Transitions

A row's review tier moves monotonically upward from machine to human (or is retracted and recorded in kg_rejections). Direct curation by an administrator or trusted curation agent starts immediately at tier = 'human'.

stateDiagram-v2
    [*] --> ProposalPending: LLM Extractor / propose_knowledge
    ProposalPending --> MaterializedMachine: Judge LLM Approves
    ProposalPending --> RejectedBlocklist: Judge or Human Rejects (kg_rejections)

    state "kg_nodes / kg_edges (tier = machine)" as MaterializedMachine {
        prov_ai_m: provenance = ai-inferred\ntier = machine
    }

    state "kg_nodes / kg_edges (tier = human)" as MaterializedHuman {
        prov_ai_h: provenance = ai-inferred\ntier = human (Human Approved Proposal)
        prov_cur_h: provenance = human-authored / human-curated\ntier = human (Direct Curation / Confirm)
    }

    MaterializedMachine --> prov_ai_h: Human Approves Proposal (review_proposals)
    MaterializedMachine --> prov_cur_h: Admin Confirms in Edge Explorer / curate_edges(confirm)
    MaterializedMachine --> RejectedBlocklist: Human Rejects Proposal (Retracts Row)
    [*] --> prov_cur_h: Direct Admin Write (curate_nodes / curate_edges)

2. The Four Provenance Values & Two Review Tiers

2.1 provenance Column Values (kg_nodes.provenance, kg_edges.provenance)

2.2 tier Column Values (kg_nodes.tier, kg_edges.tier)

3. Visibility & Filtering Across Consumption Surfaces

When an agent or human queries the Knowledge Graph, three independent gates determine whether a node or edge is returned:

4. Practical MCP & SQL Examples

4.1 Querying Only Human-Vetted Edges over /knowledge-mcp

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "traverse",
    "arguments": {
      "startNode": "Wikantik",
      "direction": "OUTBOUND",
      "maxDepth": 2,
      "minTier": "human"
    }
  }
}

4.2 Promoting an ai-inferred Edge to human-curated via /wikantik-admin-mcp

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "curate_edges",
    "arguments": {
      "op": "confirm",
      "edges": [
        {
          "sourceName": "Wikantik",
          "targetName": "PostgreSQL",
          "relationshipType": "uses"
        }
      ]
    }
  }
}

5. Mathematical Calibration of Judge Thresholds, Audit Trails, and Ontology Attribution

5.1 Confidence Thresholds & Judge Promotion Mechanics

When the chunk-level or page-level LLM extractor emits a candidate entity or relationship p_i with raw model confidence c(p_i) \in [0, 1], KnowledgeProposalService routes the candidate according to two configurable thresholds (wikantik.knowledge.extractor.min_confidence \tau_{\text{min}} and judge promotion rules):

Once queued in kg_proposals, the asynchronous LLM judge evaluates the proposal against its grounding source excerpt and records a verdict in kg_proposal_reviews. If the judge approves the proposal, the row is materialized into kg_nodes / kg_edges with:

• provenance = 'ai-inferred'
• tier = 'machine'

When a human administrator subsequently approves the proposal in /admin/knowledge-graph (Proposals tab) or via the review_proposals MCP tool, the materialized row is promoted in place to tier = 'human' while preserving provenance = 'ai-inferred'. Conversely, if a human rejects a proposal that the machine judge previously materialized, the row is retracted from kg_nodes / kg_edges and its signature (source_name, relationship_type, target_name) is inserted into kg_rejections so future re-extractions of the source page never re-propose the rejected claim.

5.2 Append-Only Edge Audit Trail (kg_edge_audit)

Every administrative mutation of an edge—whether via curate_edges(op="add" | "confirm" | "delete" | "update"), the /admin/knowledge-graph Edge Explorer, or the page editor's Knowledge Curation drawer—appends an immutable audit record to kg_edge_audit recording:

1. The acting principal (actor), timestamp (created_at), and operation type (ADD, CONFIRM, DELETE, PROMOTE, RETRACT).
2. The before-and-after (provenance, tier) tuple so administrators can measure agreement rates between the machine judge (tier = 'machine') and human curators (tier = 'human').

5.3 W3C PROV-O Mapping in the Public RDF/OWL Ontology

When EntityProjector and EdgeProjector (wikantik-ontology) materialize kg_nodes and kg_edges into the Apache Jena TDB2 store, the review tier and source_page are projected into standard W3C PROV-O (http://www.w3.org/ns/prov#) triples:

• Agent Attribution (prov:wasAttributedTo): Rows with tier = 'machine' emit prov:wasAttributedTo wk:MachineAgent, whereas rows with tier = 'human' emit prov:wasAttributedTo wk:HumanAgent.
• Source Derivation (prov:wasDerivedFrom): Every entity and edge links back to its originating wiki page resource (/id/page/<slug>). Under the fail-closed public/restricted ACL rule (2.4.26), any machine-extracted entity (provenance = 'ai-inferred') whose source_page is NULL or ACL-restricted is excluded from the public /sparql and /export/* datasets, whereas a hand-curated entity (provenance = 'human-authored', tier = 'human') without a source page is treated as an intentional public ontology assertion.

Cluster Hub: Wikantik Platform Development Hub: Architecture, MCP Protocols, and Agent Briefings (wikantik-development)