Skip to Content

Changes for page Data Model

Last modified by Robert Schaub on 2025/12/24 20:34
From version 6.1
edited by Robert Schaub
on 2025/12/15 16:56
Change comment: Imported from XAR
To version 3.1
edited by Robert Schaub
on 2025/12/11 21:35
Change comment: Imported from XAR

Summary

Details

Page properties
Content
... ... @@ -1,271 +1,38 @@
1 1  = Data Model =
2 2  
3 -This page describes the current data model for FactHarbor v0.9.1.
3 +This page describes the current data model for FactHarbor.
4 4  
5 -== Versioning Strategy ==
5 +== Core Data Model Refinements ==
6 6  
7 -Every entity in FactHarbor has a full immutable version history. This ensures:
8 -* Complete auditability
9 -* Ability to reconstruct historical state
10 -* Federation-compatible lineage tracking
11 -* Transparent evolution of claims, scenarios, and verdicts
12 -
13 -=== Core Versioning Principles ===
14 -
15 -**Immutability**:
16 -* Each version is stored independently
17 -* Versions cannot be deleted, only superseded
18 -* Historical versions remain accessible
19 -
20 -**Lineage**:
21 -* Each version links to its parent via `ParentVersionID`
22 -* Forms directed acyclic graph (DAG) of changes
23 -* Supports branching in federated environments
24 -
25 -**Provenance**:
26 -* Every version timestamped (`CreatedAt`)
27 -* Author type recorded (`AuthorType`: Human, AI, ExternalNode)
28 -* Justification captured (`JustificationText`)
29 -* Digital signatures for integrity (`SignatureHash` in Release 1.0)
30 -
31 -**Federation Support**:
32 -* Versions can originate from remote nodes
33 -* Conflict detection via lineage comparison
34 -* Parallel version trees for branching scenarios
35 -* Cross-node version synchronization
36 -
37 -=== Common Version Fields ===
38 -
39 -All versioned entities include:
40 -
41 -* **VersionID**: Unique identifier for this specific version
42 -* **ParentVersionID**: Link to previous version (null for first version)
43 -* **CreatedAt**: Timestamp (ISO 8601, UTC)
44 -* **AuthorType**: Human | AI | ExternalNode
45 -* **CreatedBy**: Foreign key to User or TechnicalUser
46 -* **JustificationText**: Brief explanation of changes
47 -* **PublicationMode**: Mode1 (draft) | Mode2 (AI-published) | Mode3 (human-reviewed)
48 -* **ReviewStatus**: Workflow state (draft|in_review|approved|rejected)
49 -* **NodeOrigin**: Node ID where version was created (for federation)
50 -* **SignatureHash**: Cryptographic signature (Release 1.0)
51 -
52 -----
53 -
54 -== Core Entity Definitions ==
55 -
56 -=== User Entities ===
57 -
58 -**USER** (base user table):
59 -* ``UserID`` (PK)
60 -* ``UserType`` (Reader|Contributor|Reviewer|Auditor|Expert|Moderator|Maintainer)
61 -* ``DisplayName``
62 -* ``Email`` (for Contributors and above)
63 -* ``RegisteredAt``
64 -* ``LastActive``
65 -* ``Status`` (active|suspended|banned)
66 -
67 -**TECHNICAL_USER** (system processes):
68 -* ``SystemID`` (PK)
69 -* ``SystemName``
70 -* ``Purpose`` (AKEL|FederationSync|BackupService|Monitor|Audit)
71 -* ``CreatedBy`` (FK to Maintainer who created this system user)
72 -* ``CreatedAt``
73 -* ``Status`` (active|paused|deprecated)
74 -* ``ApiKey`` (encrypted)
75 -* ``Permissions`` (JSON - authorized operations)
76 -
77 -**Examples of Technical Users**:
78 -* AKEL instances (AI processing)
79 -* Federation sync bots
80 -* Scheduled audit tasks
81 -* Backup services
82 -* Monitoring systems
83 -* External API integrations
84 -
85 -----
86 -
87 -=== Content Entities ===
88 -
89 89  The system relies on the following versioned core entities:
90 90  
91 -**CLAIM_CLUSTER**:
92 -* ``ClusterID`` (PK)
93 -* ``EmbeddingVectorRef``
94 -* ``Theme``
95 -* Groups related claims into topical clusters
96 -* One Cluster has many Claims
97 -* A Claim belongs to exactly one primary cluster
9 +* **CLAIM_CLUSTER**
10 +** ``ClusterID`` (PK), ``EmbeddingVectorRef``, ``Theme``
11 +** Groups related claims into topical clusters.
98 98  
99 -**CLAIM / CLAIM_VERSION**:
100 -* ``CLAIM`` is the long-lived anchor for a real-world claim
101 -* ``CLAIM_VERSION`` is an immutable snapshot that includes:
102 - * ``VersionID`` (PK)
103 - * ``ClaimID`` (FK to CLAIM)
104 - * ``ParentVersionID`` (FK to prior version, nullable)
105 - * ``Text``
106 - * ``Domain``
107 - * ``ClaimType`` (literal|metaphorical|rhetorical|supernatural)
108 - * ``Evaluability`` (empirical|subjective|non-falsifiable)
109 - * ``RiskTier`` (A|B|C) - replaced SafetyCategory for consistency
110 - * ``PublicationMode`` (Mode1|Mode2|Mode3)
111 - * ``ReviewStatus`` (draft|in_review|approved|rejected)
112 - * ``CreatedAt``, ``AuthorType``, ``CreatedBy``, ``JustificationText``
113 - * ``NodeOrigin``, ``SignatureHash``
114 - * ``Status`` (active|superseded|merged)
13 +* **CLAIM / CLAIM_VERSION**
14 +** ``CLAIM`` is the long‑lived anchor for a real‑world claim.
15 +** ``CLAIM_VERSION`` is an immutable snapshot of wording + basic metadata.
16 +** Verdicts are **NOT** attached to ClaimVersion but to Scenario.
115 115  
116 -**SCENARIO / SCENARIO_VERSION**:
117 -* ``SCENARIO`` is the anchor for a scenario across time
118 -* ``SCENARIO_VERSION`` is an immutable snapshot:
119 - * ``VersionID`` (PK)
120 - * ``ScenarioID`` (FK to SCENARIO)
121 - * ``ParentVersionID``
122 - * ``ClaimID`` (FK to CLAIM)
123 - * ``Definitions`` (JSON)
124 - * ``Boundaries`` (JSON)
125 - * ``Assumptions`` (JSON)
126 - * ``Context`` (text)
127 - * ``EvaluationMethod`` (text)
128 - * ``PublicationMode`` (Mode1|Mode2|Mode3)
129 - * ``ReviewStatus`` (draft|in_review|approved|rejected)
130 - * ``CreatedAt``, ``AuthorType``, ``CreatedBy``, ``JustificationText``
131 - * ``NodeOrigin``, ``SignatureHash``
132 - * ``Status`` (active|superseded|deprecated)
18 +* **SCENARIO / SCENARIO_VERSION**
19 +** ``SCENARIO`` represents a stable interpretive context for a claim.
20 +** ``SCENARIO_VERSION`` is an immutable snapshot of that context (definitions, assumptions, boundaries).
21 +** Verdicts are attached to SCENARIO, with verdict history in VERDICT_VERSION.
133 133  
134 -**Note**: SafetyClass removed from Scenario - risk tier is at claim level
23 +* **EVIDENCE / EVIDENCE_VERSION**
24 +** ``EVIDENCE`` is the logical source (report, article, dataset…).
25 +** ``EVIDENCE_VERSION`` is the extracted/processed snapshot (summary, reliability, etc.).
135 135  
136 -**EVIDENCE / EVIDENCE_VERSION**:
137 -* ``EVIDENCE`` is the anchor
138 -* ``EVIDENCE_VERSION`` is the versioned snapshot:
139 - * ``VersionID`` (PK)
140 - * ``EvidenceID`` (FK to EVIDENCE)
141 - * ``ParentVersionID``
142 - * ``Type`` (paper|dataset|report|transcript|expert|media)
143 - * ``Category`` (empirical|historical|rhetorical|dataset|meta-analysis)
144 - * ``Reliability`` (low|medium|high)
145 - * ``Provenance`` (URL, DOI, source metadata)
146 - * ``ExtractionMethod`` (manual|OCR|API|AKEL)
147 - * ``ContentHash`` (SHA256 of evidence content)
148 - * ``PublicationMode`` (Mode1|Mode2|Mode3)
149 - * ``ReviewStatus`` (draft|verified|disputed|retracted)
150 - * ``CreatedAt``, ``AuthorType``, ``CreatedBy``, ``JustificationText``
151 - * ``NodeOrigin``, ``SignatureHash``
152 - * ``Status`` (active|superseded)
27 +* **VERDICT / VERDICT_VERSION**
28 +** ``VERDICT`` represents “this scenario is evaluated for this claim.”
29 +** ``VERDICT_VERSION`` is an immutable snapshot of a concrete evaluation (likelihood, confidence, reasoning, timestamp).
153 153  
154 -**VERDICT / VERDICT_VERSION**:
155 -* ``VERDICT`` is the anchor
156 -* ``VERDICT_VERSION`` is the snapshot:
157 - * ``VersionID`` (PK)
158 - * ``VerdictID`` (FK to VERDICT)
159 - * ``ParentVersionID``
160 - * ``ClaimID`` (FK to CLAIM)
161 - * ``ScenarioVersionID`` (FK to specific SCENARIO_VERSION)
162 - * ``EvidenceVersionSet`` (JSON array of Evidence VersionIDs used)
163 - * ``LikelihoodRange`` (0–1, with uncertainty bounds)
164 - * ``ExplanationChain`` (JSON)
165 - * ``UncertaintyFactors`` (JSON)
166 - * ``PublicationMode`` (Mode1|Mode2|Mode3)
167 - * ``ReviewStatus`` (draft|in_review|approved|retracted)
168 - * ``CreatedAt``, ``AuthorType``, ``CreatedBy``, ``JustificationText``
169 - * ``NodeOrigin``, ``SignatureHash``
170 - * ``Status`` (current|outdated|superseded|retracted)
31 +* **SCENARIO_EVIDENCE_VERSION_LINK**
32 +** Connects ``ScenarioVersion`` ↔ ``EvidenceVersion`` (many‑to‑many).
33 +** Fields: Relevance, Direction (SUPPORTS / CONTRADICTS / NEUTRAL).
34 +** **Rule:** The link always targets VERSIONED entities, never the base tables.
171 171  
172 -----
36 +== Core Data Model ERD ==
173 173  
174 -== Many-to-Many Linking Tables ==
175 -
176 -**ScenarioEvidenceLink**:
177 -* Links scenario versions to evidence versions with relevance scoring
178 -* ``ScenarioID``, ``ScenarioVersionID``
179 -* ``EvidenceID``, ``EvidenceVersionID``
180 -* ``RelevanceScore`` (0–1) - How relevant this evidence is to this scenario
181 -* ``LinkJustification`` - Brief explanation of relevance
182 -
183 -**Purpose**:
184 -* Evidence can be used by multiple scenarios
185 -* Scenarios can draw from multiple pieces of evidence
186 -* Relevance scoring helps prioritize evidence
187 -* Version-specific linking preserves historical accuracy
188 -
189 -**ClaimCluster**:
190 -* Semantic clustering of similar claims
191 -* ``ClusterID`` (PK)
192 -* ``EmbeddingVector`` - Vector representation for semantic search
193 -* ``MemberList`` - List of ClaimIDs in this cluster
194 -* ``Theme`` - Human-readable theme description
195 -
196 -----
197 -
198 -== Key Changes in v0.9.1 ==
199 -
200 -**Updated Field Names**:
201 -* `SafetyCategory` → `RiskTier` (consistency with risk tier system A/B/C)
202 -* `SafetyClass` removed from Scenario (redundant with claim-level RiskTier)
203 -
204 -**Added Fields to All Version Entities**:
205 -* `PublicationMode` - Track Mode 1/2/3 status
206 -* `ReviewStatus` - Track workflow state
207 -* `NodeOrigin` - Federation provenance
208 -* `CreatedBy` - FK to User/TechnicalUser (clarified)
209 -
210 -**New Entity**:
211 -* `TECHNICAL_USER` - Separate system processes from human users
212 -
213 -**Clarifications**:
214 -* `ScenarioVersionID` in Verdict (not just ScenarioID) - links to specific version
215 -* `ContentHash` in Evidence - SHA256 for integrity checking
216 -
217 -----
218 -
219 -== Data Model Behavior ==
220 -
221 -=== Late-Arriving Evidence ===
222 -
223 -When new evidence versions appear:
224 -1. Existing verdicts marked as **outdated**
225 -2. Scenario relevance must be re-evaluated
226 -3. Re-evaluation engine triggers verdict recomputation
227 -4. New verdict versions created
228 -5. Users notified of updates
229 -
230 -=== Scenario Evolution ===
231 -
232 -When a scenario's assumptions or definitions change:
233 -* Creates new scenario version (not in-place update)
234 -* All dependent verdicts must be recalculated
235 -* Previous scenario versions remain accessible
236 -* Version lineage preserved
237 -
238 -=== Federated Nodes ===
239 -
240 -Each node may share partial data:
241 -* Claims and scenarios shared if relevant
242 -* Evidence metadata shared, not always full files
243 -* Version synchronization via NodeOrigin tracking
244 -* Branching allowed for divergent interpretations
245 -
246 -----
247 -
248 -== Visual Diagrams ==
249 -
250 -The following diagrams provide visual representations of the data model structure and relationships.
251 -
252 -=== Core Data Model ERD ===
253 -
254 -{{include reference="Test.FactHarborV09.Specification.Diagrams.Core Data Model ERD.WebHome"/}}
255 -
256 -=== User Roles Structure ===
257 -
258 -{{include reference="Test.FactHarborV09.Specification.Diagrams.User Roles ERD.WebHome"/}}
259 -
260 -=== Content Workflow ===
261 -
262 -{{include reference="Test.FactHarborV09.Specification.Diagrams.Content Workflow ERD.WebHome"/}}
263 -
264 -----
265 -
266 -== Related Pages ==
267 -
268 -* [[Federation & Decentralization>>FactHarbor.Specification.Federation & Decentralization.WebHome]]
269 -* [[AKEL (AI Knowledge Extraction Layer)>>FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]]
270 -* [[Architecture>>FactHarbor.Specification.Architecture.WebHome]]
271 -
38 +{{include reference="FactHarbor.Specification.Diagrams.Core Data Model ERD.WebHome"/}}