Skip to Content

Changes for page Data Model

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

Summary

Details

Page properties
Parent
... ... @@ -1,1 +1,1 @@
1 -FactHarbor.Archive.FactHarbor V0\.9\.23 Lost Data.Specification.WebHome
1 +Test.FactHarbor V0\.9\.23 Lost Data.Specification.WebHome
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,12 +54,12 @@
54 54  * **NodeOrigin**: Node ID where version was created (for federation)
55 55  * **SignatureHash**: Cryptographic signature (Release 1.0)
56 56  
52 +
57 57  == 2. Core Entity Definitions ==
58 58  
59 59  === 2.1 User Entities ===
60 60  
61 61  **USER** (base user table):
62 -
63 63  * ``UserID`` (PK)
64 64  * ``UserType`` (Reader|Contributor|Reviewer|Auditor|Expert|Moderator|Maintainer)
65 65  * ``DisplayName``
... ... @@ -69,7 +69,6 @@
69 69  * ``Status`` (active|suspended|banned)
70 70  
71 71  **TECHNICAL_USER** (system processes):
72 -
73 73  * ``SystemID`` (PK)
74 74  * ``SystemName``
75 75  * ``Purpose`` (AKEL|FederationSync|BackupService|Monitor|Audit)
... ... @@ -80,7 +80,6 @@
80 80  * ``Permissions`` (JSON - authorized operations)
81 81  
82 82  **Examples of Technical Users**:
83 -
84 84  * AKEL instances (AI processing)
85 85  * Federation sync bots
86 86  * Scheduled audit tasks
... ... @@ -88,12 +88,12 @@
88 88  * Monitoring systems
89 89  * External API integrations
90 90  
84 +
91 91  === 2.2 Content Entities ===
92 92  
93 93  The system relies on the following versioned core entities:
94 94  
95 95  **CLAIM_CLUSTER**:
96 -
97 97  * ``ClusterID`` (PK)
98 98  * ``EmbeddingVectorRef``
99 99  * ``Theme``
... ... @@ -102,86 +102,82 @@
102 102  * A Claim belongs to exactly one primary cluster
103 103  
104 104  **CLAIM / CLAIM_VERSION**:
105 -
106 106  * ``CLAIM`` is the long-lived anchor for a real-world claim
107 107  * ``CLAIM_VERSION`` is an immutable snapshot that includes:
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)
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)
121 121  
122 122  **SCENARIO / SCENARIO_VERSION**:
123 -
124 124  * ``SCENARIO`` is the anchor for a scenario across time
125 125  * ``SCENARIO_VERSION`` is an immutable snapshot:
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)
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)
140 140  
141 141  **Note**: SafetyClass removed from Scenario - risk tier is at claim level
142 142  
143 143  **EVIDENCE / EVIDENCE_VERSION**:
144 -
145 145  * ``EVIDENCE`` is the anchor
146 146  * ``EVIDENCE_VERSION`` is the versioned snapshot:
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)
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)
161 161  
162 162  **VERDICT / VERDICT_VERSION**:
163 -
164 164  * ``VERDICT`` is the anchor
165 165  * ``VERDICT_VERSION`` is the snapshot:
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)
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)
180 180  
170 +
181 181  == 3. Many-to-Many Linking Tables ==
182 182  
183 183  **ScenarioEvidenceLink**:
184 -
185 185  * Links scenario versions to evidence versions with relevance scoring
186 186  * ``ScenarioID``, ``ScenarioVersionID``
187 187  * ``EvidenceID``, ``EvidenceVersionID``
... ... @@ -189,7 +189,6 @@
189 189  * ``LinkJustification`` - Brief explanation of relevance
190 190  
191 191  **Purpose**:
192 -
193 193  * Evidence can be used by multiple scenarios
194 194  * Scenarios can draw from multiple pieces of evidence
195 195  * Relevance scoring helps prioritize evidence
... ... @@ -196,7 +196,6 @@
196 196  * Version-specific linking preserves historical accuracy
197 197  
198 198  **ClaimCluster**:
199 -
200 200  * Semantic clustering of similar claims
201 201  * ``ClusterID`` (PK)
202 202  * ``EmbeddingVector`` - Vector representation for semantic search
... ... @@ -203,15 +203,14 @@
203 203  * ``MemberList`` - List of ClaimIDs in this cluster
204 204  * ``Theme`` - Human-readable theme description
205 205  
193 +
206 206  == 4. Key Changes in v0.9.1 ==
207 207  
208 208  **Updated Field Names**:
209 -
210 210  * `SafetyCategory` → `RiskTier` (consistency with risk tier system A/B/C)
211 211  * `SafetyClass` removed from Scenario (redundant with claim-level RiskTier)
212 212  
213 213  **Added Fields to All Version Entities**:
214 -
215 215  * `PublicationMode` - Track Mode 1/2/3 status
216 216  * `ReviewStatus` - Track workflow state
217 217  * `NodeOrigin` - Federation provenance
... ... @@ -218,20 +218,18 @@
218 218  * `CreatedBy` - FK to User/TechnicalUser (clarified)
219 219  
220 220  **New Entity**:
221 -
222 222  * `TECHNICAL_USER` - Separate system processes from human users
223 223  
224 224  **Clarifications**:
225 -
226 226  * `ScenarioVersionID` in Verdict (not just ScenarioID) - links to specific version
227 227  * `ContentHash` in Evidence - SHA256 for integrity checking
228 228  
213 +
229 229  == 5. Data Model Behavior ==
230 230  
231 231  === 5.1 Late-Arriving Evidence ===
232 232  
233 233  When new evidence versions appear:
234 -
235 235  1. Existing verdicts marked as **outdated**
236 236  2. Scenario relevance must be re-evaluated
237 237  3. Re-evaluation engine triggers verdict recomputation
... ... @@ -241,7 +241,6 @@
241 241  === 5.2 Scenario Evolution ===
242 242  
243 243  When a scenario's assumptions or definitions change:
244 -
245 245  * Creates new scenario version (not in-place update)
246 246  * All dependent verdicts must be recalculated
247 247  * Previous scenario versions remain accessible
... ... @@ -250,12 +250,12 @@
250 250  === 5.3 Federated Nodes ===
251 251  
252 252  Each node may share partial data:
253 -
254 254  * Claims and scenarios shared if relevant
255 255  * Evidence metadata shared, not always full files
256 256  * Version synchronization via NodeOrigin tracking
257 257  * Branching allowed for divergent interpretations
258 258  
241 +
259 259  == 6. Visual Diagrams ==
260 260  
261 261  The following diagrams provide visual representations of the data model structure and relationships.
... ... @@ -262,7 +262,7 @@
262 262  
263 263  === 6.1 Core Data Model ERD ===
264 264  
265 -{{include reference="Test.FactHarbor V0\.9\.23 Lost Data.Specification.Diagrams.Core Data Model ERD.WebHome"}}
248 +{{include reference="Test.FactHarborV09.Specification.Diagrams.Core Data Model ERD.WebHome"}}
266 266  
267 267  === 6.2 User Roles Structure ===
268 268  
... ... @@ -278,4 +278,4 @@
278 278  * [[Federation & Decentralization>>Test.FactHarborV09.Specification.Federation & Decentralization.WebHome]]
279 279  * [[AKEL (AI Knowledge Extraction Layer)>>Test.FactHarborV09.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]]
280 280  * [[Architecture>>Test.FactHarborV09.Specification.Architecture.WebHome]]
281 -{{/include}}
264 +