Skip to Content
Last modified by Robert Schaub on 2025/12/24 20:35
From version 2.1
edited by Robert Schaub
on 2025/11/27 12:05
Change comment: There is no comment for this version
To version 4.1
edited by Robert Schaub
on 2025/11/27 12:11
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,3 +1,171 @@
1 +== 1. Overall analysis & review of the data model ==
2 +
3 +=== 1.1 Strengths of the current design ===
4 +
5 +* (((
6 +**Identity vs. version pattern**
7 +Using base entities plus version entities (CLAIM + CLAIM_VERSION, SCENARIO + SCENARIO_VERSION, etc.) is exactly how modern knowledge systems handle:
8 +
9 +* auditability
10 +* time evolution
11 +* re-evaluation triggers
12 +* federation and partial replication
13 +)))
14 +* (((
15 +**Scenario-centric reasoning**
16 +Separating //Claim// (what people argue about) from //Scenario// (interpretive frame) is very aligned with “truth landscape” style systems:
17 +
18 +* Scenarios explain //why people disagree//.
19 +* Verdicts are tied to specific scenario versions → avoids mixing incompatible assumptions.
20 +)))
21 +* **Evidence and verdicts as first-class entities**
22 +Evidence is explicit, linked to scenarios, and verdicts are per scenario. This matches good practice from fact-checking, scientific assessment panels, and trust graphs.
23 +* (((
24 +**Cluster level (CLAIM_CLUSTER)**
25 +Grouping related claims avoids duplication and lets you:
26 +
27 +* reuse scenarios across paraphrases
28 +* share embeddings / semantic search
29 +* keep the system scalable as the corpus grows.
30 +)))
31 +* (((
32 +**Explicit review layer (REVIEW_ACTION, roles, etc.)**
33 +Separating “data” from “who reviewed what” keeps the model clean, and is exactly what you want for:
34 +
35 +* governance
36 +* permissions
37 +* audit trails
38 +* future trust scoring per user / role.
39 +)))
40 +
41 +----
42 +
43 +=== 1.2 Design decisions I’m locking in (based on our discussions) ===
44 +
45 +To make the model consistent and “state-of-the-art”, I will assume the following as //current intended design//:
46 +
47 +1. (((
48 +**Claims vs Scenarios**
49 +
50 +* CLAIM is the stable identity for “what people argue about”.
51 +* CLAIM_VERSION are individual phrasings / formulations / metadata.
52 +* (((
53 +SCENARIO belongs to a **CLAIM**, not to a specific CLAIM_VERSION.
54 +Rationale:
55 +
56 +* Many different phrasings share the //same// scenario.
57 +* You avoid duplicating scenarios per wording.
58 +)))
59 +* SCENARIO_VERSION holds detailed definitions, assumptions, boundaries, etc.
60 +)))
61 +1. (((
62 +**Version-specific reasoning**
63 +
64 +* **Verdicts** are always attached to SCENARIO_VERSION (not base SCENARIO).
65 +* **Evidence links** are between SCENARIO_VERSION and EVIDENCE_VERSION.
66 +→ This is what we agreed when we said //“SCENARIO_EVIDENCE_LINK should link the respective versions instead”//.
67 +)))
68 +1. (((
69 +**Clusters**
70 +
71 +* CLAIM_CLUSTER groups Claims (semantically close claims).
72 +* It is visible in **both diagrams** (Core Data Model and Data Use).
73 +)))
74 +1. (((
75 +**Review vs data**
76 +
77 +* (((
78 +All review happens **on versioned entities**:
79 +
80 +* CLAIM_VERSION
81 +* SCENARIO_VERSION
82 +* EVIDENCE_VERSION
83 +* SCENARIO_EVIDENCE_LINK_VERSION
84 +* VERDICT_VERSION
85 +)))
86 +* REVIEW_ACTION is the generic log of //who// did //what// on //which version//.
87 +)))
88 +1. (((
89 +**Users & roles**
90 +
91 +* USER has an attribute (or a linked entity) that distinguishes **technical users** from normal accounts.
92 +* We //keep// TECHNICAL_USER as a specialisation of USER (strictly technical accounts).
93 +* All human & technical accounts can hold roles via USER_ROLE_MEMBERSHIP.
94 +* (((
95 +Roles include:
96 +
97 +* READER
98 +* CONTRIBUTOR
99 +* TRUSTED_CONTRIBUTOR
100 +* REVIEWER
101 +* MODERATOR
102 +* SYSTEM_ADMIN / MAINTAINER
103 +* FEDERATION_OPERATOR
104 +* FEDERATION_ADMIN
105 +(all present in the Data Use ERD, but as rows of ROLE rather than separate entities).
106 +)))
107 +)))
108 +
109 +----
110 +
111 +=== 1.3 Gaps / potential problems ===
112 +
113 +These are the main issues & missing areas I see:
114 +
115 +1. (((
116 +**Versioning text in chapter 5 is currently too thin (‘…’ placeholders)**
117 +
118 +* (((
119 +The spec does not yet //verbally// spell out:
120 +
121 +* the identity vs version pattern, systematically
122 +* how re-evaluation triggers are derived from version changes
123 +* how this aligns with federation (which versions are replicated where).
124 +)))
125 +)))
126 +1. (((
127 +**No explicit “provenance granularity” in the model**
128 +
129 +* (((
130 +EVIDENCE is a single entity. For more advanced use cases, you may later want:
131 +
132 +* EVIDENCE_SOURCE (the whole article/report/video)
133 +* EVIDENCE_FRAGMENT (specific paragraph/clip with its own reliability, quote, etc.)
134 +)))
135 +* For now, I’ll keep EVIDENCE/EVIDENCE_VERSION as is, but I’ll mention this as a possible extension.
136 +)))
137 +1. (((
138 +**Review target polymorphism**
139 +
140 +* (((
141 +REVIEW_ACTION can apply to multiple entity types. In the diagram this shows as multiple relationships:
142 +
143 +* CLAIM_VERSION → REVIEW_ACTION
144 +* SCENARIO_VERSION → REVIEW_ACTION
145 +* etc.
146 +)))
147 +* A more “pure” relational modeling would use a generic “subjectType + subjectId” or an intermediate “REVIEW_TARGET” table.
148 +* For readability, I’ll keep the simpler multi-edge representation and mention the polymorphism in text.
149 +)))
150 +1. (((
151 +**Federation details missing from core ERD**
152 +
153 +* There is no explicit FEDERATION_NODE / REPLICATION_LOG in the Data Model chapter.
154 +* This is ok for “core logical data model”, but I’ll add a short note that federation metadata is handled in the Federation chapter and via additional entities.
155 +)))
156 +1. (((
157 +**Automation / AKEL artifacts left implicit**
158 +
159 +* (((
160 +The Data Model chapter currently doesn’t describe:
161 +
162 +* AKEL task queues
163 +* extraction runs
164 +* model versions
165 +)))
166 +* That’s fine for now; I’ll just clarify that those belong to a “Processing / AKEL” submodel, not the core logical data model.
167 +)))
168 +
1 1  = 5. Data Model =
2 2  
3 3  The FactHarbor data model centers on four fully versioned, immutable entities:
... ... @@ -41,10 +41,10 @@
41 41   (scenarios live at the *claim* level, not per individual phrasing).
42 42  * Verdicts and Scenario–Evidence links are always attached to **versions**:
43 43  * {{code}}SCENARIO_VERSION{{/code}} +
44 - {{code}}EVIDENCE_VERSION{{/code}} →
45 - {{code}}SCENARIO_EVIDENCE_LINK_VERSION{{/code}}
212 +{{code}}EVIDENCE_VERSION{{/code}} →
213 +{{code}}SCENARIO_EVIDENCE_LINK_VERSION{{/code}}
46 46  * {{code}}SCENARIO_VERSION{{/code}} →
47 - {{code}}VERDICT_VERSION{{/code}}
215 +{{code}}VERDICT_VERSION{{/code}}
48 48  
49 49  This ensures that when a Scenario or Evidence changes, old verdicts and links
50 50  remain intact as historical records and can be revisited.
... ... @@ -172,83 +172,145 @@
172 172  
173 173  {{mermaid}}
174 174  erDiagram
343 + %% Core clusters shown for context
344 + CLAIM_CLUSTER {
345 + string ClusterID PK
346 + string EmbeddingVectorRef
347 + string Theme
348 + }
175 175  
176 - USER {
177 - string userId
178 - string displayName
179 - string email
180 - string userType %% "human" or "technical"
181 - datetime createdAt
350 + CLAIM {
351 + string ClaimID PK
352 + string ClusterID FK
353 + string Status
354 + datetime CreatedAt
182 182   }
183 183  
184 - TECHNICAL_USER {
185 - string technicalUserId
186 - string userIdFk
187 - string description
188 - string systemIdentifier
357 + CLAIM_VERSION {
358 + string ClaimVersionID PK
359 + string ClaimID FK
360 + string Text
361 + string ClaimType
362 + string Domain
363 + datetime CreatedAt
189 189   }
190 190  
191 - ROLE {
192 - string roleId
193 - string code %% e.g. READER, CONTRIBUTOR, REVIEWER, TRUSTED_CONTRIBUTOR, MODERATOR, SYSTEM_ADMIN, FEDERATION_OPERATOR, FEDERATION_ADMIN
194 - string description
195 - boolean isFederationRole
366 + SCENARIO {
367 + string ScenarioID PK
368 + string ClaimID FK
369 + string Name
370 + datetime CreatedAt
196 196   }
197 197  
198 - USER_ROLE_MEMBERSHIP {
199 - string membershipId
200 - string userIdFk
201 - string roleIdFk
202 - datetime grantedAt
203 - string grantedByUserIdFk
373 + SCENARIO_VERSION {
374 + string ScenarioVersionID PK
375 + string ScenarioID FK
376 + string Definitions
377 + string Assumptions
378 + string Boundaries
379 + datetime CreatedAt
204 204   }
205 205  
206 - REVIEW_ACTION {
207 - string reviewActionId
208 - string subjectType %% e.g. CLAIM_VERSION, SCENARIO_VERSION...
209 - string subjectVersionId
210 - string actionType %% APPROVE, REJECT, FLAG, COMMENT, REQUEST_CHANGES...
211 - string outcome %% ACCEPTED, REJECTED, ESCALATED...
212 - string comment
213 - string createdByUserIdFk
214 - datetime createdAt
382 + EVIDENCE {
383 + string EvidenceID PK
384 + string SourceType
385 + string URL
386 + float ReliabilityScore
215 215   }
216 216  
217 - %% Versioned data entities (references from the core model)
389 + EVIDENCE_VERSION {
390 + string EvidenceVersionID PK
391 + string EvidenceID FK
392 + string Summary
393 + float ReliabilityScore
394 + datetime CreatedAt
395 + }
218 218  
219 - CLAIM_VERSION {
220 - string claimVersionId
397 + VERDICT {
398 + string VerdictID PK
399 + string ScenarioID FK
221 221   }
222 222  
223 - SCENARIO_VERSION {
224 - string scenarioVersionId
402 + VERDICT_VERSION {
403 + string VerdictVersionID PK
404 + string VerdictID FK
405 + float Verdict
406 + float Confidence
407 + string Reasoning
408 + datetime CreatedAt
225 225   }
226 226  
227 - EVIDENCE_VERSION {
228 - string evidenceVersionId
411 + %% Users and roles
412 + USER {
413 + string UserID PK
414 + string Handle
415 + string Email
229 229   }
230 230  
231 - SCENARIO_EVIDENCE_LINK_VERSION {
232 - string scenarioEvidenceLinkVersionId
418 + TECHNICAL_USER {
419 + string UserID PK
420 + string SystemName
233 233   }
234 234  
235 - VERDICT_VERSION {
236 - string verdictVersionId
423 + CONTRIBUTING_USER {
424 + string UserID PK
425 + string DisplayName
237 237   }
238 238  
239 - %% Relationships
428 + TRUSTED_CONTRIBUTOR {
429 + string UserID PK
430 + string TrustLevel
431 + }
240 240  
241 - USER ||--o{ TECHNICAL_USER : may_be
242 - USER ||--o{ USER_ROLE_MEMBERSHIP : has_role
243 - ROLE ||--o{ USER_ROLE_MEMBERSHIP : assigned_to
433 + REVIEWER {
434 + string UserID PK
435 + string Domain
436 + }
244 244  
438 + EXPERT {
439 + string UserID PK
440 + string ExpertiseArea
441 + }
442 +
443 + FEDERATION_NODE {
444 + string NodeID PK
445 + string Region
446 + }
447 +
448 + FEDERATION_ADMIN {
449 + string UserID PK
450 + string Permissions
451 + }
452 +
453 + REVIEW_ACTION {
454 + string ReviewActionID PK
455 + string UserID FK
456 + string TargetEntityType
457 + string TargetEntityVersionID
458 + string ActionType
459 + string Comment
460 + datetime Timestamp
461 + }
462 +
463 + %% Inheritance / specialization (modelled as relationships)
464 + USER ||--o{ TECHNICAL_USER : "is a"
465 + USER ||--o{ CONTRIBUTING_USER : "is a"
466 +
467 + CONTRIBUTING_USER ||--o{ TRUSTED_CONTRIBUTOR : "subset"
468 + CONTRIBUTING_USER ||--o{ REVIEWER : "subset"
469 + CONTRIBUTING_USER ||--o{ EXPERT : "subset"
470 +
471 + TECHNICAL_USER ||--o{ FEDERATION_NODE : "operates"
472 + TECHNICAL_USER ||--o{ FEDERATION_ADMIN : "administers"
473 +
474 + %% Review actions on versioned entities
245 245   USER ||--o{ REVIEW_ACTION : performs
246 246  
247 - CLAIM_VERSION ||--o{ REVIEW_ACTION : is_reviewed_in
248 - SCENARIO_VERSION ||--o{ REVIEW_ACTION : is_reviewed_in
249 - EVIDENCE_VERSION ||--o{ REVIEW_ACTION : is_reviewed_in
250 - SCENARIO_EVIDENCE_LINK_VERSION ||--o{ REVIEW_ACTION : is_reviewed_in
251 - VERDICT_VERSION ||--o{ REVIEW_ACTION : is_reviewed_in
477 + REVIEW_ACTION }o--|| CLAIM_VERSION : reviews
478 + REVIEW_ACTION }o--|| SCENARIO_VERSION : reviews
479 + REVIEW_ACTION }o--|| EVIDENCE_VERSION : reviews
480 + REVIEW_ACTION }o--|| VERDICT_VERSION : reviews
481 +
252 252  {{/mermaid}}
253 253  
254 254  Notes:
... ... @@ -280,7 +280,7 @@
280 280  * It may inherit some links from earlier scenarios, or start empty depending
281 281   on the change classification (cosmetic vs. conceptual).
282 282  * All verdicts for that scenario are recalculated and stored as new
283 - {{code}}VERDICT_VERSION{{/code}} entries.
513 +{{code}}VERDICT_VERSION{{/code}} entries.
284 284  
285 285  * REVIEW_ACTIONs are always attached to the **exact version** that was seen by
286 286   the reviewer. This preserves a faithful audit trail if data later changes.