Changes for page Data Model
Last modified by Robert Schaub on 2026/02/08 08:23
From version 2.3
edited by Robert Schaub
on 2025/12/24 20:30
on 2025/12/24 20:30
Change comment:
Update document after refactoring.
Summary
-
Page properties (1 modified, 0 added, 0 removed)
Details
- Page properties
-
- Content
-
... ... @@ -5,6 +5,7 @@ 5 5 == 1. Versioning Strategy == 6 6 7 7 Every entity in FactHarbor has a full immutable version history. This ensures: 8 + 8 8 * Complete auditability 9 9 * Ability to reconstruct historical state 10 10 * Federation-compatible lineage tracking ... ... @@ -13,16 +13,19 @@ 13 13 === 1.1 Core Versioning Principles === 14 14 15 15 **Immutability**: 17 + 16 16 * Each version is stored independently 17 17 * Versions cannot be deleted, only superseded 18 18 * Historical versions remain accessible 19 19 20 20 **Lineage**: 23 + 21 21 * Each version links to its parent via `ParentVersionID` 22 22 * Forms directed acyclic graph (DAG) of changes 23 23 * Supports branching in federated environments 24 24 25 25 **Provenance**: 29 + 26 26 * Every version timestamped (`CreatedAt`) 27 27 * Author type recorded (`AuthorType`: Human, AI, ExternalNode) 28 28 * Justification captured (`JustificationText`) ... ... @@ -29,6 +29,7 @@ 29 29 * Digital signatures for integrity (`SignatureHash` in Release 1.0) 30 30 31 31 **Federation Support**: 36 + 32 32 * Versions can originate from remote nodes 33 33 * Conflict detection via lineage comparison 34 34 * Parallel version trees for branching scenarios ... ... @@ -49,7 +49,6 @@ 49 49 * **NodeOrigin**: Node ID where version was created (for federation) 50 50 * **SignatureHash**: Cryptographic signature (Release 1.0) 51 51 52 - 53 53 === 1.3 Versioning Architecture Diagram === 54 54 55 55 {{include reference="FactHarbor.Specification.Diagrams.Versioning Architecture.WebHome"/}} ... ... @@ -60,6 +60,7 @@ 60 60 === 2.1 User Entities === 61 61 62 62 **USER** (base user table): 67 + 63 63 * ``UserID`` (PK) 64 64 * ``UserType`` (Reader|Contributor|Reviewer|Auditor|Expert|Moderator|Maintainer) 65 65 * ``DisplayName`` ... ... @@ -69,6 +69,7 @@ 69 69 * ``Status`` (active|suspended|banned) 70 70 71 71 **TECHNICAL_USER** (system processes): 77 + 72 72 * ``SystemID`` (PK) 73 73 * ``SystemName`` 74 74 * ``Purpose`` (AKEL|FederationSync|BackupService|Monitor|Audit) ... ... @@ -79,6 +79,7 @@ 79 79 * ``Permissions`` (JSON - authorized operations) 80 80 81 81 **Examples of Technical Users**: 88 + 82 82 * AKEL instances (AI processing) 83 83 * Federation sync bots 84 84 * Scheduled audit tasks ... ... @@ -86,12 +86,12 @@ 86 86 * Monitoring systems 87 87 * External API integrations 88 88 89 - 90 90 === 2.2 Content Entities === 91 91 92 92 The system relies on the following versioned core entities: 93 93 94 94 **CLAIM_CLUSTER**: 101 + 95 95 * ``ClusterID`` (PK) 96 96 * ``EmbeddingVectorRef`` 97 97 * ``Theme`` ... ... @@ -100,82 +100,86 @@ 100 100 * A Claim belongs to exactly one primary cluster 101 101 102 102 **CLAIM / CLAIM_VERSION**: 110 + 103 103 * ``CLAIM`` is the long-lived anchor for a real-world claim 104 104 * ``CLAIM_VERSION`` is an immutable snapshot that includes: 105 - 106 - 107 - 108 - 109 - 110 - 111 - 112 - 113 - 114 - 115 - 116 - 117 - 113 +* ``VersionID`` (PK) 114 +* ``ClaimID`` (FK to CLAIM) 115 +* ``ParentVersionID`` (FK to prior version, nullable) 116 +* ``Text`` 117 +* ``Domain`` 118 +* ``ClaimType`` (literal|metaphorical|rhetorical|supernatural) 119 +* ``Evaluability`` (empirical|subjective|non-falsifiable) 120 +* ``RiskTier`` (A|B|C) - replaced SafetyCategory for consistency 121 +* ``PublicationMode`` (Mode1|Mode2|Mode3) 122 +* ``ReviewStatus`` (draft|in_review|approved|rejected) 123 +* ``CreatedAt``, ``AuthorType``, ``CreatedBy``, ``JustificationText`` 124 +* ``NodeOrigin``, ``SignatureHash`` 125 +* ``Status`` (active|superseded|merged) 118 118 119 119 **SCENARIO / SCENARIO_VERSION**: 128 + 120 120 * ``SCENARIO`` is the anchor for a scenario across time 121 121 * ``SCENARIO_VERSION`` is an immutable snapshot: 122 - 123 - 124 - 125 - 126 - 127 - 128 - 129 - 130 - 131 - 132 - 133 - 134 - 135 - 131 +* ``VersionID`` (PK) 132 +* ``ScenarioID`` (FK to SCENARIO) 133 +* ``ParentVersionID`` 134 +* ``ClaimID`` (FK to CLAIM) 135 +* ``Definitions`` (JSON) 136 +* ``Boundaries`` (JSON) 137 +* ``Assumptions`` (JSON) 138 +* ``Context`` (text) 139 +* ``EvaluationMethod`` (text) 140 +* ``PublicationMode`` (Mode1|Mode2|Mode3) 141 +* ``ReviewStatus`` (draft|in_review|approved|rejected) 142 +* ``CreatedAt``, ``AuthorType``, ``CreatedBy``, ``JustificationText`` 143 +* ``NodeOrigin``, ``SignatureHash`` 144 +* ``Status`` (active|superseded|deprecated) 136 136 137 137 **Note**: SafetyClass removed from Scenario - risk tier is at claim level 138 138 139 139 **EVIDENCE / EVIDENCE_VERSION**: 149 + 140 140 * ``EVIDENCE`` is the anchor 141 141 * ``EVIDENCE_VERSION`` is the versioned snapshot: 142 - 143 - 144 - 145 - 146 - 147 - 148 - 149 - 150 - 151 - 152 - 153 - 154 - 155 - 152 +* ``VersionID`` (PK) 153 +* ``EvidenceID`` (FK to EVIDENCE) 154 +* ``ParentVersionID`` 155 +* ``Type`` (paper|dataset|report|transcript|expert|media) 156 +* ``Category`` (empirical|historical|rhetorical|dataset|meta-analysis) 157 +* ``Reliability`` (low|medium|high) 158 +* ``Provenance`` (URL, DOI, source metadata) 159 +* ``ExtractionMethod`` (manual|OCR|API|AKEL) 160 +* ``ContentHash`` (SHA256 of evidence content) 161 +* ``PublicationMode`` (Mode1|Mode2|Mode3) 162 +* ``ReviewStatus`` (draft|verified|disputed|retracted) 163 +* ``CreatedAt``, ``AuthorType``, ``CreatedBy``, ``JustificationText`` 164 +* ``NodeOrigin``, ``SignatureHash`` 165 +* ``Status`` (active|superseded) 156 156 157 157 **VERDICT / VERDICT_VERSION**: 168 + 158 158 * ``VERDICT`` is the anchor 159 159 * ``VERDICT_VERSION`` is the snapshot: 160 - 161 - 162 - 163 - 164 - 165 - 166 - 167 - 168 - 169 - 170 - 171 - 172 - 173 - 171 +* ``VersionID`` (PK) 172 +* ``VerdictID`` (FK to VERDICT) 173 +* ``ParentVersionID`` 174 +* ``ClaimID`` (FK to CLAIM) 175 +* ``ScenarioVersionID`` (FK to specific SCENARIO_VERSION) 176 +* ``EvidenceVersionSet`` (JSON array of Evidence VersionIDs used) 177 +* ``LikelihoodRange`` (0–1, with uncertainty bounds) 178 +* ``ExplanationChain`` (JSON) 179 +* ``UncertaintyFactors`` (JSON) 180 +* ``PublicationMode`` (Mode1|Mode2|Mode3) 181 +* ``ReviewStatus`` (draft|in_review|approved|retracted) 182 +* ``CreatedAt``, ``AuthorType``, ``CreatedBy``, ``JustificationText`` 183 +* ``NodeOrigin``, ``SignatureHash`` 184 +* ``Status`` (current|outdated|superseded|retracted) 174 174 175 - 176 176 == 3. Many-to-Many Linking Tables == 177 177 178 178 **ScenarioEvidenceLink**: 189 + 179 179 * Links scenario versions to evidence versions with relevance scoring 180 180 * ``ScenarioID``, ``ScenarioVersionID`` 181 181 * ``EvidenceID``, ``EvidenceVersionID`` ... ... @@ -183,6 +183,7 @@ 183 183 * ``LinkJustification`` - Brief explanation of relevance 184 184 185 185 **Purpose**: 197 + 186 186 * Evidence can be used by multiple scenarios 187 187 * Scenarios can draw from multiple pieces of evidence 188 188 * Relevance scoring helps prioritize evidence ... ... @@ -189,6 +189,7 @@ 189 189 * Version-specific linking preserves historical accuracy 190 190 191 191 **ClaimCluster**: 204 + 192 192 * Semantic clustering of similar claims 193 193 * ``ClusterID`` (PK) 194 194 * ``EmbeddingVector`` - Vector representation for semantic search ... ... @@ -195,14 +195,15 @@ 195 195 * ``MemberList`` - List of ClaimIDs in this cluster 196 196 * ``Theme`` - Human-readable theme description 197 197 198 - 199 199 == 4. Key Changes Since 0.9.1 == 200 200 201 201 **Updated Field Names**: 214 + 202 202 * `SafetyCategory` → ``RiskTier`` (consistency with risk tier system A/B/C) 203 203 * `SafetyClass` removed from Scenario (redundant with claim-level RiskTier) 204 204 205 205 **Added Fields to All Version Entities**: 219 + 206 206 * `PublicationMode` - Track Mode 1/2/3 status 207 207 * `ReviewStatus` - Track workflow state 208 208 * `NodeOrigin` - Federation provenance ... ... @@ -209,18 +209,20 @@ 209 209 * `CreatedBy` - FK to User/TechnicalUser (clarified) 210 210 211 211 **New Entity**: 226 + 212 212 * `TECHNICAL_USER` - Separate system processes from human users 213 213 214 214 **Clarifications**: 230 + 215 215 * `ScenarioVersionID` in Verdict (not just ScenarioID) - links to specific version 216 216 * `ContentHash` in Evidence - SHA256 for integrity checking 217 217 218 - 219 219 == 5. Data Model Behavior == 220 220 221 221 === 5.1 Late-Arriving Evidence === 222 222 223 223 When new evidence versions appear: 239 + 224 224 1. Existing verdicts marked as **outdated** 225 225 2. Scenario relevance must be re-evaluated 226 226 3. Re-evaluation engine triggers verdict recomputation ... ... @@ -230,6 +230,7 @@ 230 230 === 5.2 Scenario Evolution === 231 231 232 232 When a scenario's assumptions or definitions change: 249 + 233 233 * Creates new scenario version (not in-place update) 234 234 * All dependent verdicts must be recalculated 235 235 * Previous scenario versions remain accessible ... ... @@ -238,12 +238,12 @@ 238 238 === 5.3 Federated Nodes === 239 239 240 240 Each node may share partial data: 258 + 241 241 * Claims and scenarios shared if relevant 242 242 * Evidence metadata shared, not always full files 243 243 * Version synchronization via NodeOrigin tracking 244 244 * Branching allowed for divergent interpretations 245 245 246 - 247 247 == 6. Visual Diagrams == 248 248 249 249 The following diagrams provide visual representations of the data model structure and relationships. ... ... @@ -264,6 +264,5 @@ 264 264 == 7. Related Pages == 265 265 266 266 * [[Federation & Decentralization>>FactHarbor.Specification.Federation & Decentralization.WebHome]] 267 -* [[AKEL (AI Knowledge Extraction Layer)>>FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] 268 -* [[Architecture>>FactHarbor.Specification.Architecture.WebHome]] 269 - 284 +* [[AKEL (AI Knowledge Extraction Layer)>>Archive.FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] 285 +* [[Architecture>>Archive.FactHarbor.Specification.Architecture.WebHome]]