Skip to Content

Changes for page Data Model

Last modified by Robert Schaub on 2025/12/24 20:34
From version 1.2
edited by Robert Schaub
on 2025/12/16 20:40
Change comment: Update document after refactoring.
To version 1.6
edited by Robert Schaub
on 2025/12/24 20:33
Change comment: Update document after refactoring.

Summary

Details

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