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

Summary

Details

Page properties
Content
... ... @@ -1,7 +5,3 @@
1 -(((
2 -
3 -)))
4 -
5 5  = 5. Data Model =
6 6  
7 7  The FactHarbor data model centers on four fully versioned, immutable entities:
... ... @@ -45,10 +45,10 @@
45 45   (scenarios live at the *claim* level, not per individual phrasing).
46 46  * Verdicts and Scenario–Evidence links are always attached to **versions**:
47 47  * {{code}}SCENARIO_VERSION{{/code}} +
48 -{{code}}EVIDENCE_VERSION{{/code}} →
49 -{{code}}SCENARIO_EVIDENCE_LINK_VERSION{{/code}}
44 + {{code}}EVIDENCE_VERSION{{/code}} →
45 + {{code}}SCENARIO_EVIDENCE_LINK_VERSION{{/code}}
50 50  * {{code}}SCENARIO_VERSION{{/code}} →
51 -{{code}}VERDICT_VERSION{{/code}}
47 + {{code}}VERDICT_VERSION{{/code}}
52 52  
53 53  This ensures that when a Scenario or Evidence changes, old verdicts and links
54 54  remain intact as historical records and can be revisited.
... ... @@ -61,9 +61,99 @@
61 61  The convention is that fields ending in {{code}}Id{{/code}} are primary keys,
62 62  and fields with {{code}}...IdFk{{/code}} are foreign keys.
63 63  
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"/}}
60 +{{mermaid}}
61 +erDiagram
62 + CLAIM_CLUSTER {
63 + string ClusterID PK
64 + string EmbeddingVectorRef
65 + string Theme
66 + }
66 66  
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 +
67 67  **Important points:**
68 68  
69 69  * Scenarios and Evidence are **linked via their versions**
... ... @@ -84,14 +84,6 @@
84 84  * Roles and role assignments
85 85  * Review actions on versioned entities
86 86  
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 -
95 95  {{mermaid}}
96 96  erDiagram
97 97   %% Core clusters shown for context
... ... @@ -232,16 +232,9 @@
232 232   REVIEW_ACTION }o--|| SCENARIO_VERSION : reviews
233 233   REVIEW_ACTION }o--|| EVIDENCE_VERSION : reviews
234 234   REVIEW_ACTION }o--|| VERDICT_VERSION : reviews
313 +
235 235  {{/mermaid}}
236 236  
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 -
245 245  Notes:
246 246  
247 247  * Most roles (READER, CONTRIBUTOR, TRUSTED_CONTRIBUTOR, REVIEWER, MODERATOR,
... ... @@ -271,7 +271,7 @@
271 271  * It may inherit some links from earlier scenarios, or start empty depending
272 272   on the change classification (cosmetic vs. conceptual).
273 273  * All verdicts for that scenario are recalculated and stored as new
274 -{{code}}VERDICT_VERSION{{/code}} entries.
345 + {{code}}VERDICT_VERSION{{/code}} entries.
275 275  
276 276  * REVIEW_ACTIONs are always attached to the **exact version** that was seen by
277 277   the reviewer. This preserves a faithful audit trail if data later changes.
... ... @@ -308,173 +308,3 @@
308 308  Federation-specific entities (such as {{code}}FEDERATION_NODE{{/code}},
309 309  replication logs, and trust rules) are described in the Federation &
310 310  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 -)))