Skip to Content

Changes for page Data Model

Last modified by Robert Schaub on 2026/02/08 08:23
From version 2.4
edited by Robert Schaub
on 2026/01/20 20:25
Change comment: Renamed back-links.
To version 2.3
edited by Robert Schaub
on 2025/12/24 20:30
Change comment: Update document after refactoring.

Summary

Details

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