Workflows

This chapter defines the core workflows used across the FactHarbor system.

Each workflow describes:

• Purpose
• Participants
• Steps
• Automation vs. manual work

1. Claim Workflow

Purpose: Transform raw text or input material into a normalized, classified, deduplicated, and versioned claim.

Participants:

• Contributor
• AKEL
• Reviewer

Steps:

1. Ingestion: User submits text/URL; AKEL extracts claims.
2. Normalization: Standardize wording, reduce ambiguity.
3. Classification: Domain, Evaluability, Safety (AKEL draft → Human confirm).
4. Duplicate Detection: Check embeddings for existing claims.
5. Version Creation: Store new ClaimVersion.
6. Cluster Assignment: Assign to Claim Cluster.
7. Scenario Linking: Connect to existing or draft new scenarios.
8. Publication: Make visible.

Flow: Ingest → Normalize → Classify → Deduplicate → Cluster → Version → Publish

2. Scenario Workflow

Purpose: Define the specific analytic contexts needed to evaluate each claim.

Steps:

1. Scenario Proposal: Drafted by contributor or AKEL.
2. Required Fields: Definitions, Assumptions, ContextBoundary, EvaluationMethod, SafetyClass.
3. Safety Interception: AKEL flags non-falsifiable or unsafe content.
4. Conflict Check: Merge similar scenarios, flag contradictions.
5. Reviewer Validation: Ensure clarity and validity.
6. Expert Approval: Mandatory for high-risk domains.
7. Version Storage: Save ScenarioVersion.

Flow: Draft → Validate → Safety Check → Review → Expert → Version → Activate

3. Evidence Workflow

Purpose: Structure, classify, validate, version, and link evidence to scenarios.

Steps:

1. Submission: File, URL, or text.
2. Metadata Extraction: Type, Category, Provenance, ReliabilityHints.
3. Relevance Check: Verify applicability to scenario.
4. Reliability Assessment: Score reliability (Reviewer + Expert).
5. Link Creation: Create ScenarioEvidenceLink with relevance score.
6. Versioning: Update EvidenceVersion.

Flow: Submit → Extract → Relevance → Reliability → Link → Version

4. Verdict Workflow

Purpose: Generate likelihood estimates per scenario based on evidence.

Steps:

1. Aggregation: Collect linked evidence for a specific scenario.
2. Draft Verdict: AKEL proposes likelihood and uncertainty for that scenario.
3. Reasoning: AKEL drafts explanation chain.
4. Validation: Reviewer checks logic and hallucinations.
5. Expert Review: Required for sensitive topics.
6. Storage: Save VerdictVersion.

Flow: Aggregate → Draft → Reasoning → Review → Expert → Version

5. Re-evaluation Workflow

Purpose: Keep verdicts current when inputs change.

Steps:

1. Trigger: Evidence update, Scenario change, or Contradiction.
2. Impact Analysis: Identify affected nodes.
3. Re-calculation: AKEL proposes new likelihoods.
4. Validation: Human review.
5. Storage: New version.

Flow: Trigger → Analyze → Recompute → Review → Version

6. Federation Synchronization Workflow

Purpose: Exchange structured data between nodes.

Steps:

1. Detect Version Changes.
2. Build Signed Bundle (Merkle tree).
3. Push/Pull to Peers.
4. Validate Signatures & Lineage.
5. Resolve Conflicts (Merge/Fork).
6. Trigger Re-evaluation.

7. User Role & Review Workflow

Purpose: Ensure correctness and safety.

Steps:

1. Submission.
2. Auto-check (AKEL).
3. Reviewer Validation.
4. Expert Validation (if needed).
5. Moderator Oversight (if flagged).

8. AKEL Workflow

Stages:

• Input Understanding
• Scenario Drafting
• Evidence Processing
• Verdict Drafting
• Safety & Integrity
• Human Approval

9. Global Trigger Flow (Cascade)

Sources: Claim/Scenario/Evidence change, Verdict contradiction, Federation update.

Flow: Trigger → Dependency Graph → Re-evaluation → Updated Verdicts