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

Summary

Details

Page properties
Content
... ... @@ -1,3 +1,7 @@
1 +(((
2 +
3 +)))
4 +
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}}
48 +{{code}}EVIDENCE_VERSION{{/code}} →
49 +{{code}}SCENARIO_EVIDENCE_LINK_VERSION{{/code}}
46 46  * {{code}}SCENARIO_VERSION{{/code}} →
47 - {{code}}VERDICT_VERSION{{/code}}
51 +{{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.
... ... @@ -57,99 +57,9 @@
57 57  The convention is that fields ending in {{code}}Id{{/code}} are primary keys,
58 58  and fields with {{code}}...IdFk{{/code}} are foreign keys.
59 59  
60 -{{mermaid}}
61 -erDiagram
62 - CLAIM_CLUSTER {
63 - string ClusterID PK
64 - string EmbeddingVectorRef
65 - string Theme
66 - }
64 +{{comment}} Core Data Model ERD (Mermaid, from /Specification/Diagrams/Data Model) {{/comment}}
65 +{{include document="FactHarbor.Playground.Core Data Model ERD Page (from Specification chat).WebHome" reference="FactHarbor.Playground.data.Core Data Model ERD Page (from Specification chat).WebHome"/}}
67 67  
68 - CLAIM {
69 - string ClaimID PK
70 - string ClusterID FK
71 - string Status
72 - datetime CreatedAt
73 - }
74 -
75 - CLAIM_VERSION {
76 - string ClaimVersionID PK
77 - string ClaimID FK
78 - string Text
79 - string ClaimType
80 - string Domain
81 - datetime CreatedAt
82 - }
83 -
84 - SCENARIO {
85 - string ScenarioID PK
86 - string ClaimID FK
87 - string Name
88 - datetime CreatedAt
89 - }
90 -
91 - SCENARIO_VERSION {
92 - string ScenarioVersionID PK
93 - string ScenarioID FK
94 - string Definitions
95 - string Assumptions
96 - string Boundaries
97 - datetime CreatedAt
98 - }
99 -
100 - EVIDENCE {
101 - string EvidenceID PK
102 - string SourceType
103 - string URL
104 - float ReliabilityScore
105 - }
106 -
107 - EVIDENCE_VERSION {
108 - string EvidenceVersionID PK
109 - string EvidenceID FK
110 - string Summary
111 - float ReliabilityScore
112 - datetime CreatedAt
113 - }
114 -
115 - SCENARIO_EVIDENCE_LINK {
116 - string LinkID PK
117 - string ScenarioVersionID FK
118 - string EvidenceVersionID FK
119 - float Relevance
120 - string Direction
121 - }
122 -
123 - VERDICT {
124 - string VerdictID PK
125 - string ScenarioID FK
126 - }
127 -
128 - VERDICT_VERSION {
129 - string VerdictVersionID PK
130 - string VerdictID FK
131 - float Verdict
132 - float Confidence
133 - string Reasoning
134 - datetime CreatedAt
135 - }
136 -
137 - CLAIM_CLUSTER ||--o{ CLAIM : contains
138 - CLAIM ||--o{ CLAIM_VERSION : versions
139 -
140 - CLAIM ||--o{ SCENARIO : has
141 - SCENARIO ||--o{ SCENARIO_VERSION : versions
142 -
143 - EVIDENCE ||--o{ EVIDENCE_VERSION : versions
144 -
145 - SCENARIO_VERSION ||--o{ SCENARIO_EVIDENCE_LINK : links
146 - EVIDENCE_VERSION ||--o{ SCENARIO_EVIDENCE_LINK : linked
147 -
148 - SCENARIO ||--o{ VERDICT : assessed
149 - VERDICT ||--o{ VERDICT_VERSION : versions
150 -
151 -{{/mermaid}}
152 -
153 153  **Important points:**
154 154  
155 155  * Scenarios and Evidence are **linked via their versions**
... ... @@ -170,6 +170,14 @@
170 170  * Roles and role assignments
171 171  * Review actions on versioned entities
172 172  
87 +{{comment}} Data Use ERD (Mermaid, from /Specification/Diagrams/Data Use ERD) {{/comment}}
88 +{{include document="FactHarbor.Playground.Data Use ERD Page (from Specification chat).WebHome" reference="FactHarbor.Playground.data.Data Use ERD Page (from Specification chat).WebHome"/}}
89 +
90 += Data Use ERD (Roles, Review & Versioned Entities) =
91 +
92 +This diagram shows how users, roles, and review actions relate to the
93 +versioned core entities.
94 +
173 173  {{mermaid}}
174 174  erDiagram
175 175   %% Core clusters shown for context
... ... @@ -310,9 +310,16 @@
310 310   REVIEW_ACTION }o--|| SCENARIO_VERSION : reviews
311 311   REVIEW_ACTION }o--|| EVIDENCE_VERSION : reviews
312 312   REVIEW_ACTION }o--|| VERDICT_VERSION : reviews
313 -
314 314  {{/mermaid}}
315 315  
237 +{{info}}
238 +This diagram focuses on *who* uses and reviews *which* versioned entities.
239 +USER is the base type; TECHNICAL_USER and CONTRIBUTING_USER are specializations.
240 +Other roles (REVIEWER, EXPERT, TRUSTED_CONTRIBUTOR, FEDERATION_ADMIN, FEDERATION_NODE)
241 +are modelled as specializations or technical subtypes.
242 +{{/info}}
243 +
244 +
316 316  Notes:
317 317  
318 318  * Most roles (READER, CONTRIBUTOR, TRUSTED_CONTRIBUTOR, REVIEWER, MODERATOR,
... ... @@ -342,7 +342,7 @@
342 342  * It may inherit some links from earlier scenarios, or start empty depending
343 343   on the change classification (cosmetic vs. conceptual).
344 344  * All verdicts for that scenario are recalculated and stored as new
345 - {{code}}VERDICT_VERSION{{/code}} entries.
274 +{{code}}VERDICT_VERSION{{/code}} entries.
346 346  
347 347  * REVIEW_ACTIONs are always attached to the **exact version** that was seen by
348 348   the reviewer. This preserves a faithful audit trail if data later changes.
... ... @@ -379,3 +379,173 @@
379 379  Federation-specific entities (such as {{code}}FEDERATION_NODE{{/code}},
380 380  replication logs, and trust rules) are described in the Federation &
381 381  Decentralization chapter and build on top of the core data model defined here.
311 +
312 +----
313 +
314 +== 1. Overall analysis & review of the data model ==
315 +
316 +=== 1.1 Strengths of the current design ===
317 +
318 +* (((
319 +**Identity vs. version pattern**
320 +Using base entities plus version entities (CLAIM + CLAIM_VERSION, SCENARIO + SCENARIO_VERSION, etc.) is exactly how modern knowledge systems handle:
321 +
322 +* auditability
323 +* time evolution
324 +* re-evaluation triggers
325 +* federation and partial replication
326 +)))
327 +* (((
328 +**Scenario-centric reasoning**
329 +Separating //Claim// (what people argue about) from //Scenario// (interpretive frame) is very aligned with “truth landscape” style systems:
330 +
331 +* Scenarios explain //why people disagree//.
332 +* Verdicts are tied to specific scenario versions → avoids mixing incompatible assumptions.
333 +)))
334 +* **Evidence and verdicts as first-class entities**
335 +Evidence is explicit, linked to scenarios, and verdicts are per scenario. This matches good practice from fact-checking, scientific assessment panels, and trust graphs.
336 +* (((
337 +**Cluster level (CLAIM_CLUSTER)**
338 +Grouping related claims avoids duplication and lets you:
339 +
340 +* reuse scenarios across paraphrases
341 +* share embeddings / semantic search
342 +* keep the system scalable as the corpus grows.
343 +)))
344 +* (((
345 +**Explicit review layer (REVIEW_ACTION, roles, etc.)**
346 +Separating “data” from “who reviewed what” keeps the model clean, and is exactly what you want for:
347 +
348 +* governance
349 +* permissions
350 +* audit trails
351 +* future trust scoring per user / role.
352 +)))
353 +
354 +----
355 +
356 +=== 1.2 Design decisions I’m locking in (based on our discussions) ===
357 +
358 +To make the model consistent and “state-of-the-art”, I will assume the following as //current intended design//:
359 +
360 +1. (((
361 +**Claims vs Scenarios**
362 +
363 +* CLAIM is the stable identity for “what people argue about”.
364 +* CLAIM_VERSION are individual phrasings / formulations / metadata.
365 +* (((
366 +SCENARIO belongs to a **CLAIM**, not to a specific CLAIM_VERSION.
367 +Rationale:
368 +
369 +* Many different phrasings share the //same// scenario.
370 +* You avoid duplicating scenarios per wording.
371 +)))
372 +* SCENARIO_VERSION holds detailed definitions, assumptions, boundaries, etc.
373 +)))
374 +1. (((
375 +**Version-specific reasoning**
376 +
377 +* **Verdicts** are always attached to SCENARIO_VERSION (not base SCENARIO).
378 +* **Evidence links** are between SCENARIO_VERSION and EVIDENCE_VERSION.
379 +→ This is what we agreed when we said //“SCENARIO_EVIDENCE_LINK should link the respective versions instead”//.
380 +)))
381 +1. (((
382 +**Clusters**
383 +
384 +* CLAIM_CLUSTER groups Claims (semantically close claims).
385 +* It is visible in **both diagrams** (Core Data Model and Data Use).
386 +)))
387 +1. (((
388 +**Review vs data**
389 +
390 +* (((
391 +All review happens **on versioned entities**:
392 +
393 +* CLAIM_VERSION
394 +* SCENARIO_VERSION
395 +* EVIDENCE_VERSION
396 +* SCENARIO_EVIDENCE_LINK_VERSION
397 +* VERDICT_VERSION
398 +)))
399 +* REVIEW_ACTION is the generic log of //who// did //what// on //which version//.
400 +)))
401 +1. (((
402 +**Users & roles**
403 +
404 +* USER has an attribute (or a linked entity) that distinguishes **technical users** from normal accounts.
405 +* We //keep// TECHNICAL_USER as a specialisation of USER (strictly technical accounts).
406 +* All human & technical accounts can hold roles via USER_ROLE_MEMBERSHIP.
407 +* (((
408 +Roles include:
409 +
410 +* READER
411 +* CONTRIBUTOR
412 +* TRUSTED_CONTRIBUTOR
413 +* REVIEWER
414 +* MODERATOR
415 +* SYSTEM_ADMIN / MAINTAINER
416 +* FEDERATION_OPERATOR
417 +* FEDERATION_ADMIN
418 +(all present in the Data Use ERD, but as rows of ROLE rather than separate entities).
419 +)))
420 +)))
421 +
422 +----
423 +
424 +=== 1.3 Gaps / potential problems ===
425 +
426 +These are the main issues & missing areas I see:
427 +
428 +1. (((
429 +**Versioning text in chapter 5 is currently too thin (‘…’ placeholders)**
430 +
431 +* (((
432 +The spec does not yet //verbally// spell out:
433 +
434 +* the identity vs version pattern, systematically
435 +* how re-evaluation triggers are derived from version changes
436 +* how this aligns with federation (which versions are replicated where).
437 +)))
438 +)))
439 +1. (((
440 +**No explicit “provenance granularity” in the model**
441 +
442 +* (((
443 +EVIDENCE is a single entity. For more advanced use cases, you may later want:
444 +
445 +* EVIDENCE_SOURCE (the whole article/report/video)
446 +* EVIDENCE_FRAGMENT (specific paragraph/clip with its own reliability, quote, etc.)
447 +)))
448 +* For now, I’ll keep EVIDENCE/EVIDENCE_VERSION as is, but I’ll mention this as a possible extension.
449 +)))
450 +1. (((
451 +**Review target polymorphism**
452 +
453 +* (((
454 +REVIEW_ACTION can apply to multiple entity types. In the diagram this shows as multiple relationships:
455 +
456 +* CLAIM_VERSION → REVIEW_ACTION
457 +* SCENARIO_VERSION → REVIEW_ACTION
458 +* etc.
459 +)))
460 +* A more “pure” relational modeling would use a generic “subjectType + subjectId” or an intermediate “REVIEW_TARGET” table.
461 +* For readability, I’ll keep the simpler multi-edge representation and mention the polymorphism in text.
462 +)))
463 +1. (((
464 +**Federation details missing from core ERD**
465 +
466 +* There is no explicit FEDERATION_NODE / REPLICATION_LOG in the Data Model chapter.
467 +* 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.
468 +)))
469 +1. (((
470 +**Automation / AKEL artifacts left implicit**
471 +
472 +* (((
473 +The Data Model chapter currently doesn’t describe:
474 +
475 +* AKEL task queues
476 +* extraction runs
477 +* model versions
478 +)))
479 +* That’s fine for now; I’ll just clarify that those belong to a “Processing / AKEL” submodel, not the core logical data model.
480 +)))