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

Summary

Details

Page properties
Content
... ... @@ -1,162 +160,3 @@
1 -(((
2 -
3 -)))
4 -
5 -= 5. Data Model =
6 -
7 -The FactHarbor data model centers on four fully versioned, immutable entities:
8 -
9 -* **Claim**
10 -* **Scenario**
11 -* **Evidence**
12 -* **Verdict**
13 -
14 -These entities form the structured **“truth landscape”** for each claim.
15 -The model is explicitly **versioned**, **traceable**, and **federation-ready**.
16 -
17 -To keep the system auditable and explainable, FactHarbor uses a consistent
18 -**identity vs. version** pattern:
19 -
20 -* Identity entities (e.g. {{code}}CLAIM{{/code}}, {{code}}SCENARIO{{/code}})
21 - define *what* something is in a stable sense.
22 -* Version entities (e.g. {{code}}CLAIM_VERSION{{/code}}, {{code}}SCENARIO_VERSION{{/code}})
23 - define *how that thing looked at a given point in time*.
24 -
25 -All reasoning (e.g. verdicts, review actions) is attached to **versions**, never to
26 -mutable identities.
27 -
28 -----
29 -
30 -= 5.1 Core entities and versioning pattern =
31 -
32 -(% class="wikitable" %)
33 -| **Logical concept** | **Identity entity** | **Version entity** | **Notes**
34 -| Claim (what people argue about) | {{code}}CLAIM{{/code}} | {{code}}CLAIM_VERSION{{/code}} | Claim text, phrasing, and metadata live in {{code}}CLAIM_VERSION{{/code}}. The identity {{code}}CLAIM{{/code}} stays stable across rephrasings.
35 -| Scenario (interpretive frame) | {{code}}SCENARIO{{/code}} | {{code}}SCENARIO_VERSION{{/code}} | A SCENARIO belongs to a CLAIM. Its versions capture evolving definitions, assumptions, and boundaries.
36 -| Evidence (source / datapoint) | {{code}}EVIDENCE{{/code}} | {{code}}EVIDENCE_VERSION{{/code}} | Identity of a source vs. specific extractions / updates over time.
37 -| Verdict (assessment) | {{code}}VERDICT{{/code}} | {{code}}VERDICT_VERSION{{/code}} | A VERDICT is defined per SCENARIO; VERDICT_VERSION captures the history of assessments.
38 -| Scenario–Evidence link | {{code}}SCENARIO_EVIDENCE_LINK{{/code}} | {{code}}SCENARIO_EVIDENCE_LINK_VERSION{{/code}} | Links bind scenario versions to evidence versions with relevance & direction.
39 -| Claim cluster (semantic group) | {{code}}CLAIM_CLUSTER{{/code}} | – | Groups semantically related claims; mainly for discovery and navigation.
40 -
41 -Key design decisions:
42 -
43 -* A {{code}}CLAIM{{/code}} belongs to exactly one {{code}}CLAIM_CLUSTER{{/code}}.
44 -* A {{code}}SCENARIO{{/code}} belongs to exactly one {{code}}CLAIM{{/code}}
45 - (scenarios live at the *claim* level, not per individual phrasing).
46 -* Verdicts and Scenario–Evidence links are always attached to **versions**:
47 -* {{code}}SCENARIO_VERSION{{/code}} +
48 -{{code}}EVIDENCE_VERSION{{/code}} →
49 -{{code}}SCENARIO_EVIDENCE_LINK_VERSION{{/code}}
50 -* {{code}}SCENARIO_VERSION{{/code}} →
51 -{{code}}VERDICT_VERSION{{/code}}
52 -
53 -This ensures that when a Scenario or Evidence changes, old verdicts and links
54 -remain intact as historical records and can be revisited.
55 -
56 -----
57 -
58 -= 5.2 Core Data Model ERD (expanded, versioned) =
59 -
60 -The following Mermaid ER diagram shows the main entities and their relationships.
61 -The convention is that fields ending in {{code}}Id{{/code}} are primary keys,
62 -and fields with {{code}}...IdFk{{/code}} are foreign keys.
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 -**Important points:**
68 -
69 -* Scenarios and Evidence are **linked via their versions**
70 - ({{code}}SCENARIO_VERSION{{/code}} and {{code}}EVIDENCE_VERSION{{/code}}).
71 -* Verdicts are **per ScenarioVersion** and stored in {{code}}VERDICT_VERSION{{/code}}.
72 -* {{code}}CLAIM_CLUSTER{{/code}} is shared across diagrams; it is shown here and in the Data Use / Review model.
73 -
74 -All version entities are immutable: once created, they are never changed, only
75 -superseded by newer versions.
76 -
77 -----
78 -
79 -= 5.3 Data Use & Review ERD =
80 -
81 -The **Data Use** model captures who does what with which versioned data:
82 -
83 -* Users (including technical users)
84 -* Roles and role assignments
85 -* Review actions on versioned entities
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 -
91 -Notes:
92 -
93 -* Most roles (READER, CONTRIBUTOR, TRUSTED_CONTRIBUTOR, REVIEWER, MODERATOR,
94 - SYSTEM_ADMIN, FEDERATION_OPERATOR, FEDERATION_ADMIN, …) are represented as rows
95 - in {{code}}ROLE{{/code}}.
96 -* {{code}}TECHNICAL_USER{{/code}} captures strictly technical accounts (API keys,
97 - node-to-node federation agents, batch jobs). All other roles can, in principle,
98 - be held by both human and technical users where appropriate.
99 -* A {{code}}READER{{/code}} normally does **not** perform REVIEW_ACTIONs, while
100 - roles like REVIEWER, TRUSTED_CONTRIBUTOR, MODERATOR, and some federation roles
101 - do.
102 -
103 -----
104 -
105 -= 5.4 Versioning and re-evaluation behavior =
106 -
107 -This section ties the data model to the re-evaluation logic
108 -(described in more detail in the Versioning and Automation chapters).
109 -
110 -* When a new {{code}}EVIDENCE_VERSION{{/code}} is created:
111 -* All related {{code}}SCENARIO_EVIDENCE_LINK_VERSION{{/code}} entries referencing
112 - that evidence version are candidates for re-assessment.
113 -* Related {{code}}VERDICT_VERSION{{/code}} entries may become **outdated** and
114 - are queued for re-evaluation.
115 -
116 -* When a new {{code}}SCENARIO_VERSION{{/code}} is created:
117 -* It may inherit some links from earlier scenarios, or start empty depending
118 - on the change classification (cosmetic vs. conceptual).
119 -* All verdicts for that scenario are recalculated and stored as new
120 -{{code}}VERDICT_VERSION{{/code}} entries.
121 -
122 -* REVIEW_ACTIONs are always attached to the **exact version** that was seen by
123 - the reviewer. This preserves a faithful audit trail if data later changes.
124 -
125 -* In a federated environment, nodes can choose:
126 -* which identity entities to replicate (CLAIM, SCENARIO, EVIDENCE, VERDICT)
127 -* which versioned entities to replicate (e.g. only accepted VERDICT_VERSIONs,
128 - only EVIDENCE_VERSIONs above a reliability threshold, etc.)
129 -
130 -----
131 -
132 -= 5.5 Behavioral Notes =
133 -
134 -== 5.5.1 Late-Arriving Evidence ==
135 -
136 -New evidence versions can make existing verdicts **outdated** and may trigger
137 -re-evaluation cascades. This is handled by the global trigger and automation
138 -architecture (see the Versioning & Automation chapters).
139 -
140 -== 5.5.2 Scenario Evolution ==
141 -
142 -Scenario changes create new SCENARIO_VERSIONs; dependent verdicts and
143 -Scenario–Evidence links are re-assessed. Old versions remain available for
144 -historical comparison and reproducibility.
145 -
146 -== 5.5.3 Federation ==
147 -
148 -Federated nodes can replicate subsets of the graph, including:
149 -
150 -* Claims and Scenarios of local interest
151 -* Evidence metadata (without full content)
152 -* Verdict lineages used for local decision-making
153 -
154 -Federation-specific entities (such as {{code}}FEDERATION_NODE{{/code}},
155 -replication logs, and trust rules) are described in the Federation &
156 -Decentralization chapter and build on top of the core data model defined here.
157 -
158 -----
159 -
160 160  == 1. Overall analysis & review of the data model ==
161 161  
162 162  === 1.1 Strengths of the current design ===
... ... @@ -324,3 +324,155 @@
324 324  )))
325 325  * That’s fine for now; I’ll just clarify that those belong to a “Processing / AKEL” submodel, not the core logical data model.
326 326  )))
168 +
169 += 5. Data Model =
170 +
171 +The FactHarbor data model centers on four fully versioned, immutable entities:
172 +
173 +* **Claim**
174 +* **Scenario**
175 +* **Evidence**
176 +* **Verdict**
177 +
178 +These entities form the structured **“truth landscape”** for each claim.
179 +The model is explicitly **versioned**, **traceable**, and **federation-ready**.
180 +
181 +To keep the system auditable and explainable, FactHarbor uses a consistent
182 +**identity vs. version** pattern:
183 +
184 +* Identity entities (e.g. {{code}}CLAIM{{/code}}, {{code}}SCENARIO{{/code}})
185 + define *what* something is in a stable sense.
186 +* Version entities (e.g. {{code}}CLAIM_VERSION{{/code}}, {{code}}SCENARIO_VERSION{{/code}})
187 + define *how that thing looked at a given point in time*.
188 +
189 +All reasoning (e.g. verdicts, review actions) is attached to **versions**, never to
190 +mutable identities.
191 +
192 +----
193 +
194 += 5.1 Core entities and versioning pattern =
195 +
196 +(% class="wikitable" %)
197 +| **Logical concept** | **Identity entity** | **Version entity** | **Notes**
198 +| Claim (what people argue about) | {{code}}CLAIM{{/code}} | {{code}}CLAIM_VERSION{{/code}} | Claim text, phrasing, and metadata live in {{code}}CLAIM_VERSION{{/code}}. The identity {{code}}CLAIM{{/code}} stays stable across rephrasings.
199 +| Scenario (interpretive frame) | {{code}}SCENARIO{{/code}} | {{code}}SCENARIO_VERSION{{/code}} | A SCENARIO belongs to a CLAIM. Its versions capture evolving definitions, assumptions, and boundaries.
200 +| Evidence (source / datapoint) | {{code}}EVIDENCE{{/code}} | {{code}}EVIDENCE_VERSION{{/code}} | Identity of a source vs. specific extractions / updates over time.
201 +| Verdict (assessment) | {{code}}VERDICT{{/code}} | {{code}}VERDICT_VERSION{{/code}} | A VERDICT is defined per SCENARIO; VERDICT_VERSION captures the history of assessments.
202 +| Scenario–Evidence link | {{code}}SCENARIO_EVIDENCE_LINK{{/code}} | {{code}}SCENARIO_EVIDENCE_LINK_VERSION{{/code}} | Links bind scenario versions to evidence versions with relevance & direction.
203 +| Claim cluster (semantic group) | {{code}}CLAIM_CLUSTER{{/code}} | – | Groups semantically related claims; mainly for discovery and navigation.
204 +
205 +Key design decisions:
206 +
207 +* A {{code}}CLAIM{{/code}} belongs to exactly one {{code}}CLAIM_CLUSTER{{/code}}.
208 +* A {{code}}SCENARIO{{/code}} belongs to exactly one {{code}}CLAIM{{/code}}
209 + (scenarios live at the *claim* level, not per individual phrasing).
210 +* Verdicts and Scenario–Evidence links are always attached to **versions**:
211 +* {{code}}SCENARIO_VERSION{{/code}} +
212 +{{code}}EVIDENCE_VERSION{{/code}} →
213 +{{code}}SCENARIO_EVIDENCE_LINK_VERSION{{/code}}
214 +* {{code}}SCENARIO_VERSION{{/code}} →
215 +{{code}}VERDICT_VERSION{{/code}}
216 +
217 +This ensures that when a Scenario or Evidence changes, old verdicts and links
218 +remain intact as historical records and can be revisited.
219 +
220 +----
221 +
222 += 5.2 Core Data Model ERD (expanded, versioned) =
223 +
224 +The following Mermaid ER diagram shows the main entities and their relationships.
225 +The convention is that fields ending in {{code}}Id{{/code}} are primary keys,
226 +and fields with {{code}}...IdFk{{/code}} are foreign keys.
227 +
228 +{{comment}} Core Data Model ERD (Mermaid, from /Specification/Diagrams/Data Model) {{/comment}}
229 +{{include document="FactHarbor.Playground.Core Data Model ERD Page (from Specification chat).WebHome"/}}
230 +
231 +**Important points:**
232 +
233 +* Scenarios and Evidence are **linked via their versions**
234 + ({{code}}SCENARIO_VERSION{{/code}} and {{code}}EVIDENCE_VERSION{{/code}}).
235 +* Verdicts are **per ScenarioVersion** and stored in {{code}}VERDICT_VERSION{{/code}}.
236 +* {{code}}CLAIM_CLUSTER{{/code}} is shared across diagrams; it is shown here and in the Data Use / Review model.
237 +
238 +All version entities are immutable: once created, they are never changed, only
239 +superseded by newer versions.
240 +
241 +----
242 +
243 += 5.3 Data Use & Review ERD (expanded, versioned) =
244 +
245 +The **Data Use** model captures who does what with which versioned data:
246 +
247 +* Users (including technical users)
248 +* Roles and role assignments
249 +* Review actions on versioned entities
250 +
251 +{{comment}} Data Use ERD (Mermaid, from /Specification/Diagrams/Data Use ERD) {{/comment}}
252 +{{include document="FactHarbor.Playground.Data Use ERD Page (from Specification chat).WebHome"/}}
253 +
254 +Notes:
255 +
256 +* Most roles (READER, CONTRIBUTOR, TRUSTED_CONTRIBUTOR, REVIEWER, MODERATOR,
257 + SYSTEM_ADMIN, FEDERATION_OPERATOR, FEDERATION_ADMIN, …) are represented as rows
258 + in {{code}}ROLE{{/code}}.
259 +* {{code}}TECHNICAL_USER{{/code}} captures strictly technical accounts (API keys,
260 + node-to-node federation agents, batch jobs). All other roles can, in principle,
261 + be held by both human and technical users where appropriate.
262 +* A {{code}}READER{{/code}} normally does **not** perform REVIEW_ACTIONs, while
263 + roles like REVIEWER, TRUSTED_CONTRIBUTOR, MODERATOR, and some federation roles
264 + do.
265 +
266 +----
267 +
268 += 5.4 Versioning and re-evaluation behavior =
269 +
270 +This section ties the data model to the re-evaluation logic
271 +(described in more detail in the Versioning and Automation chapters).
272 +
273 +* When a new {{code}}EVIDENCE_VERSION{{/code}} is created:
274 +* All related {{code}}SCENARIO_EVIDENCE_LINK_VERSION{{/code}} entries referencing
275 + that evidence version are candidates for re-assessment.
276 +* Related {{code}}VERDICT_VERSION{{/code}} entries may become **outdated** and
277 + are queued for re-evaluation.
278 +
279 +* When a new {{code}}SCENARIO_VERSION{{/code}} is created:
280 +* It may inherit some links from earlier scenarios, or start empty depending
281 + on the change classification (cosmetic vs. conceptual).
282 +* All verdicts for that scenario are recalculated and stored as new
283 +{{code}}VERDICT_VERSION{{/code}} entries.
284 +
285 +* REVIEW_ACTIONs are always attached to the **exact version** that was seen by
286 + the reviewer. This preserves a faithful audit trail if data later changes.
287 +
288 +* In a federated environment, nodes can choose:
289 +* which identity entities to replicate (CLAIM, SCENARIO, EVIDENCE, VERDICT)
290 +* which versioned entities to replicate (e.g. only accepted VERDICT_VERSIONs,
291 + only EVIDENCE_VERSIONs above a reliability threshold, etc.)
292 +
293 +----
294 +
295 += 5.5 Behavioral Notes =
296 +
297 +== 5.5.1 Late-Arriving Evidence ==
298 +
299 +New evidence versions can make existing verdicts **outdated** and may trigger
300 +re-evaluation cascades. This is handled by the global trigger and automation
301 +architecture (see the Versioning & Automation chapters).
302 +
303 +== 5.5.2 Scenario Evolution ==
304 +
305 +Scenario changes create new SCENARIO_VERSIONs; dependent verdicts and
306 +Scenario–Evidence links are re-assessed. Old versions remain available for
307 +historical comparison and reproducibility.
308 +
309 +== 5.5.3 Federation ==
310 +
311 +Federated nodes can replicate subsets of the graph, including:
312 +
313 +* Claims and Scenarios of local interest
314 +* Evidence metadata (without full content)
315 +* Verdict lineages used for local decision-making
316 +
317 +Federation-specific entities (such as {{code}}FEDERATION_NODE{{/code}},
318 +replication logs, and trust rules) are described in the Federation &
319 +Decentralization chapter and build on top of the core data model defined here.