Skip to Content
Last modified by Robert Schaub on 2025/12/24 20:35
From version 8.2
edited by Robert Schaub
on 2025/11/27 23:15
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,7 +1,171 @@
1 -(((
2 -
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
3 3  )))
14 +* (((
15 +**Scenario-centric reasoning**
16 +Separating //Claim// (what people argue about) from //Scenario// (interpretive frame) is very aligned with “truth landscape” style systems:
4 4  
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 +
5 5  = 5. Data Model =
6 6  
7 7  The FactHarbor data model centers on four fully versioned, immutable entities:
... ... @@ -61,13 +61,6 @@
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"/}}
66 -
67 -= Core Data Model ERD (Versioned) =
68 -
69 -This diagram shows the full core data model with all versioned entities.
70 -
71 71  {{mermaid}}
72 72  erDiagram
73 73   CLAIM_CLUSTER {
... ... @@ -158,14 +158,9 @@
158 158  
159 159   SCENARIO ||--o{ VERDICT : assessed
160 160   VERDICT ||--o{ VERDICT_VERSION : versions
318 +
161 161  {{/mermaid}}
162 162  
163 -{{info}}
164 -All key entities are explicitly versioned here (…VERSION tables).
165 -This reflects the versioning requirements in the textual Data Model chapter.
166 -{{/info}}
167 -
168 -
169 169  **Important points:**
170 170  
171 171  * Scenarios and Evidence are **linked via their versions**
... ... @@ -178,7 +178,7 @@
178 178  
179 179  ----
180 180  
181 -= 5.3 Data Use & Review ERD =
333 += 5.3 Data Use & Review ERD (expanded, versioned) =
182 182  
183 183  The **Data Use** model captures who does what with which versioned data:
184 184  
... ... @@ -186,14 +186,6 @@
186 186  * Roles and role assignments
187 187  * Review actions on versioned entities
188 188  
189 -{{comment}} Data Use ERD (Mermaid, from /Specification/Diagrams/Data Use ERD) {{/comment}}
190 -{{include document="FactHarbor.Playground.Data Use ERD Page (from Specification chat).WebHome" reference="FactHarbor.Playground.data.Data Use ERD Page (from Specification chat).WebHome"/}}
191 -
192 -= Data Use ERD (Roles, Review & Versioned Entities) =
193 -
194 -This diagram shows how users, roles, and review actions relate to the
195 -versioned core entities.
196 -
197 197  {{mermaid}}
198 198  erDiagram
199 199   %% Core clusters shown for context
... ... @@ -334,17 +334,9 @@
334 334   REVIEW_ACTION }o--|| SCENARIO_VERSION : reviews
335 335   REVIEW_ACTION }o--|| EVIDENCE_VERSION : reviews
336 336   REVIEW_ACTION }o--|| VERDICT_VERSION : reviews
481 +
337 337  {{/mermaid}}
338 338  
339 -{{info}}
340 -This diagram focuses on *who* uses and reviews *which* versioned entities.
341 -USER is the base type; TECHNICAL_USER and CONTRIBUTING_USER are specializations.
342 -Other roles (REVIEWER, EXPERT, TRUSTED_CONTRIBUTOR, FEDERATION_ADMIN, FEDERATION_NODE)
343 -are modelled as specializations or technical subtypes.
344 -{{/info}}
345 -
346 -
347 -
348 348  Notes:
349 349  
350 350  * Most roles (READER, CONTRIBUTOR, TRUSTED_CONTRIBUTOR, REVIEWER, MODERATOR,
... ... @@ -411,191 +411,3 @@
411 411  Federation-specific entities (such as {{code}}FEDERATION_NODE{{/code}},
412 412  replication logs, and trust rules) are described in the Federation &
413 413  Decentralization chapter and build on top of the core data model defined here.
414 -
415 -
416 -
417 -USER
418 -├── TECHNICAL_USER
419 -│  ├── FEDERATION_ADMIN
420 -│  └── AKEL_AGENT (optional future)
421 -
422 -READER
423 -└── CONTRIBUTING_USER
424 - ├── TRUSTED_CONTRIBUTOR
425 - ├── REVIEWER
426 - ├── EXPERT
427 - ├── MODERATOR
428 -
429 -
430 -ADMIN
431 -
432 -FEDERATION_ADMIN (administrative, but human)
433 -
434 -
435 -== 1. Overall analysis & review of the data model ==
436 -
437 -=== 1.1 Strengths of the current design ===
438 -
439 -* (((
440 -**Identity vs. version pattern**
441 -Using base entities plus version entities (CLAIM + CLAIM_VERSION, SCENARIO + SCENARIO_VERSION, etc.) is exactly how modern knowledge systems handle:
442 -
443 -* auditability
444 -* time evolution
445 -* re-evaluation triggers
446 -* federation and partial replication
447 -)))
448 -* (((
449 -**Scenario-centric reasoning**
450 -Separating //Claim// (what people argue about) from //Scenario// (interpretive frame) is very aligned with “truth landscape” style systems:
451 -
452 -* Scenarios explain //why people disagree//.
453 -* Verdicts are tied to specific scenario versions → avoids mixing incompatible assumptions.
454 -)))
455 -* **Evidence and verdicts as first-class entities**
456 -Evidence is explicit, linked to scenarios, and verdicts are per scenario. This matches good practice from fact-checking, scientific assessment panels, and trust graphs.
457 -* (((
458 -**Cluster level (CLAIM_CLUSTER)**
459 -Grouping related claims avoids duplication and lets you:
460 -
461 -* reuse scenarios across paraphrases
462 -* share embeddings / semantic search
463 -* keep the system scalable as the corpus grows.
464 -)))
465 -* (((
466 -**Explicit review layer (REVIEW_ACTION, roles, etc.)**
467 -Separating “data” from “who reviewed what” keeps the model clean, and is exactly what you want for:
468 -
469 -* governance
470 -* permissions
471 -* audit trails
472 -* future trust scoring per user / role.
473 -)))
474 -
475 -----
476 -
477 -=== 1.2 Design decisions I’m locking in (based on our discussions) ===
478 -
479 -To make the model consistent and “state-of-the-art”, I will assume the following as //current intended design//:
480 -
481 -1. (((
482 -**Claims vs Scenarios**
483 -
484 -* CLAIM is the stable identity for “what people argue about”.
485 -* CLAIM_VERSION are individual phrasings / formulations / metadata.
486 -* (((
487 -SCENARIO belongs to a **CLAIM**, not to a specific CLAIM_VERSION.
488 -Rationale:
489 -
490 -* Many different phrasings share the //same// scenario.
491 -* You avoid duplicating scenarios per wording.
492 -)))
493 -* SCENARIO_VERSION holds detailed definitions, assumptions, boundaries, etc.
494 -)))
495 -1. (((
496 -**Version-specific reasoning**
497 -
498 -* **Verdicts** are always attached to SCENARIO_VERSION (not base SCENARIO).
499 -* **Evidence links** are between SCENARIO_VERSION and EVIDENCE_VERSION.
500 -→ This is what we agreed when we said //“SCENARIO_EVIDENCE_LINK should link the respective versions instead”//.
501 -)))
502 -1. (((
503 -**Clusters**
504 -
505 -* CLAIM_CLUSTER groups Claims (semantically close claims).
506 -* It is visible in **both diagrams** (Core Data Model and Data Use).
507 -)))
508 -1. (((
509 -**Review vs data**
510 -
511 -* (((
512 -All review happens **on versioned entities**:
513 -
514 -* CLAIM_VERSION
515 -* SCENARIO_VERSION
516 -* EVIDENCE_VERSION
517 -* SCENARIO_EVIDENCE_LINK_VERSION
518 -* VERDICT_VERSION
519 -)))
520 -* REVIEW_ACTION is the generic log of //who// did //what// on //which version//.
521 -)))
522 -1. (((
523 -**Users & roles**
524 -
525 -* USER has an attribute (or a linked entity) that distinguishes **technical users** from normal accounts.
526 -* We //keep// TECHNICAL_USER as a specialisation of USER (strictly technical accounts).
527 -* All human & technical accounts can hold roles via USER_ROLE_MEMBERSHIP.
528 -* (((
529 -Roles include:
530 -
531 -* READER
532 -* CONTRIBUTOR
533 -* TRUSTED_CONTRIBUTOR
534 -* REVIEWER
535 -* MODERATOR
536 -* SYSTEM_ADMIN / MAINTAINER
537 -* FEDERATION_OPERATOR
538 -* FEDERATION_ADMIN
539 -(all present in the Data Use ERD, but as rows of ROLE rather than separate entities).
540 -)))
541 -)))
542 -
543 -----
544 -
545 -=== 1.3 Gaps / potential problems ===
546 -
547 -These are the main issues & missing areas I see:
548 -
549 -1. (((
550 -**Versioning text in chapter 5 is currently too thin (‘…’ placeholders)**
551 -
552 -* (((
553 -The spec does not yet //verbally// spell out:
554 -
555 -* the identity vs version pattern, systematically
556 -* how re-evaluation triggers are derived from version changes
557 -* how this aligns with federation (which versions are replicated where).
558 -)))
559 -)))
560 -1. (((
561 -**No explicit “provenance granularity” in the model**
562 -
563 -* (((
564 -EVIDENCE is a single entity. For more advanced use cases, you may later want:
565 -
566 -* EVIDENCE_SOURCE (the whole article/report/video)
567 -* EVIDENCE_FRAGMENT (specific paragraph/clip with its own reliability, quote, etc.)
568 -)))
569 -* For now, I’ll keep EVIDENCE/EVIDENCE_VERSION as is, but I’ll mention this as a possible extension.
570 -)))
571 -1. (((
572 -**Review target polymorphism**
573 -
574 -* (((
575 -REVIEW_ACTION can apply to multiple entity types. In the diagram this shows as multiple relationships:
576 -
577 -* CLAIM_VERSION → REVIEW_ACTION
578 -* SCENARIO_VERSION → REVIEW_ACTION
579 -* etc.
580 -)))
581 -* A more “pure” relational modeling would use a generic “subjectType + subjectId” or an intermediate “REVIEW_TARGET” table.
582 -* For readability, I’ll keep the simpler multi-edge representation and mention the polymorphism in text.
583 -)))
584 -1. (((
585 -**Federation details missing from core ERD**
586 -
587 -* There is no explicit FEDERATION_NODE / REPLICATION_LOG in the Data Model chapter.
588 -* 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.
589 -)))
590 -1. (((
591 -**Automation / AKEL artifacts left implicit**
592 -
593 -* (((
594 -The Data Model chapter currently doesn’t describe:
595 -
596 -* AKEL task queues
597 -* extraction runs
598 -* model versions
599 -)))
600 -* That’s fine for now; I’ll just clarify that those belong to a “Processing / AKEL” submodel, not the core logical data model.
601 -)))