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

Summary

Details

Page properties
Content
... ... @@ -1,171 +1,7 @@
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
1 +(((
2 +
13 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 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 -
169 169  = 5. Data Model =
170 170  
171 171  The FactHarbor data model centers on four fully versioned, immutable entities:
... ... @@ -225,6 +225,13 @@
225 225  The convention is that fields ending in {{code}}Id{{/code}} are primary keys,
226 226  and fields with {{code}}...IdFk{{/code}} are foreign keys.
227 227  
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 +
228 228  {{mermaid}}
229 229  erDiagram
230 230   CLAIM_CLUSTER {
... ... @@ -315,9 +315,14 @@
315 315  
316 316   SCENARIO ||--o{ VERDICT : assessed
317 317   VERDICT ||--o{ VERDICT_VERSION : versions
318 -
319 319  {{/mermaid}}
320 320  
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 +
321 321  **Important points:**
322 322  
323 323  * Scenarios and Evidence are **linked via their versions**
... ... @@ -330,7 +330,7 @@
330 330  
331 331  ----
332 332  
333 -= 5.3 Data Use & Review ERD (expanded, versioned) =
181 += 5.3 Data Use & Review ERD =
334 334  
335 335  The **Data Use** model captures who does what with which versioned data:
336 336  
... ... @@ -338,6 +338,14 @@
338 338  * Roles and role assignments
339 339  * Review actions on versioned entities
340 340  
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 +
341 341  {{mermaid}}
342 342  erDiagram
343 343   %% Core clusters shown for context
... ... @@ -478,9 +478,17 @@
478 478   REVIEW_ACTION }o--|| SCENARIO_VERSION : reviews
479 479   REVIEW_ACTION }o--|| EVIDENCE_VERSION : reviews
480 480   REVIEW_ACTION }o--|| VERDICT_VERSION : reviews
481 -
482 482  {{/mermaid}}
483 483  
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 +
484 484  Notes:
485 485  
486 486  * Most roles (READER, CONTRIBUTOR, TRUSTED_CONTRIBUTOR, REVIEWER, MODERATOR,
... ... @@ -547,3 +547,191 @@
547 547  Federation-specific entities (such as {{code}}FEDERATION_NODE{{/code}},
548 548  replication logs, and trust rules) are described in the Federation &
549 549  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 +)))