Skip to Content

Changes for page Requirements

Last modified by Robert Schaub on 2025/12/24 20:34
From version 2.1
edited by Robert Schaub
on 2025/12/12 09:32
Change comment: Imported from XAR
To version 1.1
edited by Robert Schaub
on 2025/12/11 18:37
Change comment: Imported from XAR

Summary

Details

Page properties
Content
... ... @@ -1,91 +1,442 @@
1 1  = Requirements =
2 2  
3 -This chapter defines the requirements for FactHarbor.
3 +This chapter defines all functional, non-functional, user-role, and federation requirements for FactHarbor.
4 4  
5 -== User Roles ==
5 +It answers:
6 6  
7 -=== Reader ===
8 -* **Responsibilities**: Browse, search, view scenarios/verdicts, flag issues.
9 -* **Permissions**: Read-only access.
10 -* **Limitations**: Cannot change content.
7 +* Who can do what in the system?
8 +* What workflows must FactHarbor support?
9 +* What quality, transparency, and federation guarantees must be met?
11 11  
12 -=== Contributor ===
13 -* **Responsibilities**: Submit claims, draft scenarios, attach evidence.
14 -* **Permissions**: Create/Edit drafts, comment.
15 -* **Limitations**: Cannot publish without review.
11 +----
16 16  
17 -=== Reviewer ===
18 -* **Responsibilities**: Validate contributions, check consistency.
19 -* **Permissions**: Change status to "Published" or "Rejected".
13 += User Roles =
20 20  
21 -=== Expert ===
22 -* **Responsibilities**: Domain-specific judgment, refine assumptions.
23 -* **Permissions**: Attach expert annotations, propose re-evaluation.
15 +== Reader ==
24 24  
25 -=== Moderator ===
26 -* **Responsibilities**: Handle abuse, spam, and manipulation.
27 -* **Permissions**: Hide content, ban users.
17 +Responsibilities:
28 28  
29 -=== Maintainer / Administrator ===
30 -* **Responsibilities**: Node config, security, role assignment.
31 -* **Permissions**: System configuration.
19 +* Browse and search claims
20 +* View scenarios, evidence, verdicts, and timelines
21 +* Compare scenarios and explore assumptions
22 +* Flag issues, errors, contradictions, or suspicious patterns
32 32  
33 -=== AKEL (AI) ===
34 -* **Responsibilities**: Propose drafts, normalize, classify.
35 -* **Permissions**: Create machine-generated drafts.
36 -* **Limitations**: Never publishes without human approval.
24 +Permissions:
37 37  
38 -== Functional Requirements ==
26 +* Read-only access to all published claims, scenarios, evidence, and verdicts
27 +* Use filters, search, and visualization tools (“truth landscape”, timelines, scenario comparison, etc.)
28 +* Create personal views (saved searches, bookmarks, etc.)
39 39  
40 -=== Claim Intake & Normalization ===
41 -* **FR1**: Support text, URL, document input.
42 -* **FR2**: Normalize wording while preserving original.
43 -* **FR3**: Classify by domain/type.
44 -* **FR4**: Cluster similar claims.
30 +Limitations:
45 45  
46 -=== Scenario System ===
47 -* **FR5**: Create scenarios linked to clusters.
48 -* **FR6**: Require Definitions, Assumptions, Boundaries.
49 -* **FR7**: Full versioning.
50 -* **FR8**: Side-by-side comparison.
32 +* Cannot change shared content
33 +* Cannot publish new claims, scenarios, or verdicts
51 51  
52 -=== Evidence Management ===
53 -* **FR9**: Ingest external sources.
54 -* **FR10**: Assess reliability/quality.
55 -* **FR11**: Link evidence to multiple scenarios.
35 +----
56 56  
57 -=== Verdicts & Truth Landscape ===
58 -* **FR12**: Likelihood-based verdicts **per scenario**.
59 -* **FR13**: Aggregate into Truth Landscape.
60 -* **FR14**: Show evolution over time.
37 +== Contributor ==
61 61  
62 -=== Workflow & Audit ===
63 -* **FR15**: Draft -> Review -> Publish states.
64 -* **FR16**: Moderation tools.
65 -* **FR17**: Full audit trail.
39 +Responsibilities:
66 66  
67 -== Federation Requirements ==
41 +* Submit claims
42 +* Propose new claim clusters (if automatic clustering is insufficient)
43 +* Draft scenarios (definitions, assumptions, boundaries)
44 +* Attach evidence (sources, documents, links, datasets)
45 +* Suggest verdict drafts and uncertainty ranges
46 +* Respond to reviewer or expert feedback
68 68  
69 -* **FR18**: Node autonomy.
70 -* **FR19**: Configurable data sharing.
71 -* **FR20**: Sync with conflict handling.
72 -* **FR21**: Node discovery.
48 +Permissions:
73 73  
74 -== Non-Functional Requirements ==
50 +* Everything a Reader can do
51 +* Create and edit **draft** claims, scenarios, evidence links, and verdict drafts
52 +* Comment on existing content and discuss assumptions
53 +* Propose corrections to misclassified or outdated content
75 75  
76 -* **NFR1 - Transparency**: Visible reasoning and AKEL labeling.
77 -* **NFR2 - Security**: Role-based access, secure storage.
78 -* **NFR3 - Privacy**: Minimal data retention, compliance hooks.
79 -* **NFR4 - Performance**: < 2s response (POC).
80 -* **NFR5 - Scalability**: Support thousands of users (Release 1.0).
81 -* **NFR6 - Interoperability**: Open API.
82 -* **NFR7 - Observability**: Metrics and logs.
83 -* **NFR8 - Maintainability**: Modular architecture.
84 -* **NFR9 - Usability**: Progressive disclosure of complexity.
55 +Limitations:
85 85  
86 -== Release Levels ==
57 +* Cannot *publish* or mark content as “reviewed” or “approved”
58 +* Cannot override expert or maintainer decisions
59 +* Cannot change system-level settings, roles, or federation configuration
87 87  
88 -* **POC (Fully Automated)**: Single node. **"Text to Truth Landscape"** workflow. Automated extraction, scenario generation, and verdict computation.
89 -* **Beta 0**: Few nodes, external testers. Expanded manual workflows and moderation.
90 -* **Release 1.0**: Scalable, Federated, High Automation. Multi-node federation.
61 +----
91 91  
63 +== Reviewer ==
64 +
65 +Responsibilities:
66 +
67 +* Review contributions from Contributors and AKEL drafts
68 +* Check internal consistency and clarity of scenarios
69 +* Validate that evidence is correctly linked and described
70 +* Ensure verdicts match the evidence and stated assumptions
71 +* Reject, request change, or accept content
72 +
73 +Permissions:
74 +
75 +* Everything a Contributor can do
76 +* Change content status from `draft` → `in review` → `published` / `rejected`
77 +* Send content back to Contributors with comments
78 +* Flag content for expert review
79 +
80 +Limitations:
81 +
82 +* Cannot modify system-wide configuration or federation topology
83 +* Cannot unilaterally change expert conclusions without process
84 +
85 +----
86 +
87 +== Expert ==
88 +
89 +Responsibilities:
90 +
91 +* Provide domain-specific judgment on scenarios, evidence, and verdicts
92 +* Refine assumptions and definitions in complex or ambiguous topics
93 +* Identify subtle biases, missing evidence, or misinterpretations
94 +* Propose improved verdicts and uncertainty assessments
95 +
96 +Permissions:
97 +
98 +* Everything a Reviewer can do
99 +* Attach expert annotations and signed opinions to scenarios and verdicts
100 +* Propose re-evaluation of already published content based on new evidence
101 +
102 +Limitations:
103 +
104 +* Expert status is scoped to specific domains
105 +* Cannot bypass moderation, abuse policies, or legal constraints
106 +
107 +----
108 +
109 +== Moderator ==
110 +
111 +Responsibilities:
112 +
113 +* Handle abuse reports, spam, harassment, and coordinated manipulation
114 +* Enforce community guidelines and legal constraints
115 +* Manage user bans, content takedowns, and visibility restrictions
116 +
117 +Permissions:
118 +
119 +* Hide or temporarily disable access to abusive content
120 +* Ban or restrict users in line with policy
121 +* Edit or redact sensitive content (e.g., doxxing, illegal material)
122 +
123 +Limitations:
124 +
125 +* Does not change factual verdicts except where required for legal / safety reasons
126 +* Substantive fact changes must go through the review / expert process
127 +
128 +----
129 +
130 +== Maintainer / Administrator ==
131 +
132 +Responsibilities:
133 +
134 +* Maintain node configuration, security settings, and backups
135 +* Configure AKEL, storage, federation endpoints, and performance tuning
136 +* Manage role assignments (who is Reviewer, Expert, Moderator, etc.)
137 +* Approve software updates and schema migrations
138 +
139 +Permissions:
140 +
141 +* All read/write access to configuration, but not necessarily content editorial authority
142 +* Define organization-level policies (e.g., which sources are allowed by default)
143 +
144 +Limitations:
145 +
146 +* Editorial decisions on controversial topics follow governance rules, not arbitrary admin choice
147 +
148 +----
149 +
150 +== AKEL (AI Knowledge Extraction Layer) ==
151 +
152 +Responsibilities:
153 +
154 +* Propose drafts — never final decisions
155 +* Normalize claims and extract candidate clusters
156 +* Draft scenarios, evidence candidates, and preliminary verdict suggestions
157 +* Propose re-evaluation when new evidence appears
158 +
159 +Permissions:
160 +
161 +* Create and update **machine-generated drafts** and suggestions
162 +* Never directly publish content without human approval
163 +
164 +Limitations:
165 +
166 +* AKEL output is always labeled as AI-generated draft
167 +* Must be reviewable, auditable, and overridable by humans
168 +
169 +----
170 +
171 += Functional Requirements =
172 +
173 +This section defines what the system must **do**.
174 +
175 +== Claim Intake & Normalization ==
176 +
177 +=== FR1 – Claim Intake ===
178 +
179 +The system must support Claim creation from:
180 +
181 +* Free-text input
182 +* URLs (web pages, articles, posts)
183 +* Uploaded documents and transcripts
184 +* Structured feeds (optional, e.g. from partner platforms)
185 +
186 +Accepted sources:
187 +
188 +* Text entered by users
189 +* URLs
190 +* Uploaded documents
191 +* Transcripts
192 +* Automated ingestion (optional federation input)
193 +* AKEL extraction from multi-claim texts
194 +
195 +=== FR2 – Claim Normalization ===
196 +
197 +* Convert diverse inputs into short, structured, declarative claims
198 +* Preserve original phrasing for reference
199 +* Avoid hidden reinterpretation; differences between original and normalized phrasing must be visible
200 +
201 +=== FR3 – Claim Classification ===
202 +
203 +* Classify claims by topic, domain, and type (e.g., quantitative, causal, normative)
204 +* Suggest which node / experts are relevant
205 +
206 +=== FR4 – Claim Clustering ===
207 +
208 +* Group similar claims into Claim Clusters
209 +* Allow manual correction of cluster membership
210 +* Provide explanation why two claims are considered “same cluster”
211 +
212 +----
213 +
214 +== Scenario System ==
215 +
216 +=== FR5 – Scenario Creation ===
217 +
218 +* Contributors, Reviewers, and Experts can create scenarios
219 +* AKEL can propose draft scenarios
220 +* Each scenario is tied to exactly one Claim Cluster
221 +
222 +=== FR6 – Required Scenario Fields ===
223 +
224 +Each scenario includes:
225 +
226 +* Definitions (key terms)
227 +* Assumptions (explicit, testable where possible)
228 +* Boundaries (time, geography, population, conditions)
229 +* Scope of evidence considered
230 +* Intended decision / context (optional)
231 +
232 +=== FR7 – Scenario Versioning ===
233 +
234 +* Every change to a scenario creates a new version
235 +* Previous versions remain accessible with timestamps and rationale
236 +
237 +=== FR8 – Scenario Comparison ===
238 +
239 +* Users can compare scenarios side by side
240 +* Show differences in assumptions, definitions, and evidence sets
241 +
242 +----
243 +
244 +== Evidence Management ==
245 +
246 +=== FR9 – Evidence Ingestion ===
247 +
248 +* Attach external sources (articles, studies, datasets, reports, transcripts) to Scenarios
249 +* Allow multiple pieces of evidence per Scenario
250 +
251 +=== FR10 – Evidence Assessment ===
252 +
253 +For each piece of evidence:
254 +
255 +* Assign reliability / quality ratings
256 +* Capture who rated it and why
257 +* Indicate known limitations, biases, or conflicts of interest
258 +
259 +=== FR11 – Evidence Linking ===
260 +
261 +* Link one piece of evidence to multiple scenarios if relevant
262 +* Make dependencies explicit (e.g., “Scenario A uses subset of evidence used in Scenario B”)
263 +
264 +----
265 +
266 +== Verdicts & Truth Landscape ==
267 +
268 +=== FR12 – Scenario Verdicts ===
269 +
270 +For each Scenario:
271 +
272 +* Provide a **probability- or likelihood-based verdict**
273 +* Capture uncertainty and reasoning
274 +* Distinguish between AKEL draft and human-approved verdict
275 +
276 +=== FR13 – Truth Landscape ===
277 +
278 +* Aggregate all scenario-specific verdicts into a “truth landscape” for a claim
279 +* Make disagreements visible rather than collapsing them into a single binary result
280 +
281 +=== FR14 – Time Evolution ===
282 +
283 +* Show how verdicts and evidence evolve over time
284 +* Allow users to see “as of date X, what did we know?”
285 +
286 +----
287 +
288 +== Workflow, Moderation & Audit ==
289 +
290 +=== FR15 – Workflow States ===
291 +
292 +* Draft → In Review → Published / Rejected
293 +* Separate states for Claims, Scenarios, Evidence, and Verdicts
294 +
295 +=== FR16 – Moderation & Abuse Handling ===
296 +
297 +* Allow Moderators to hide content or lock edits for abuse or legal reasons
298 +* Keep internal audit trail even if public view is restricted
299 +
300 +=== FR17 – Audit Trail ===
301 +
302 +* Every significant action (create, edit, publish, delete/hide) is logged with:
303 + * Who did it
304 + * When
305 + * What changed
306 + * Why (short comment, optional but recommended)
307 +
308 +----
309 +
310 += Federation Requirements =
311 +
312 +FactHarbor is designed to operate as a **federated network of nodes**.
313 +
314 +=== FR18 – Node Autonomy ===
315 +
316 +* Each node can run independently (local policies, local users, local moderation)
317 +* Nodes decide which other nodes to federate with
318 +
319 +=== FR19 – Data Sharing Modes ===
320 +
321 +Nodes must be able to:
322 +
323 +* Share claims and summaries only
324 +* Share selected claims, scenarios, and verdicts
325 +* Share full underlying evidence metadata where allowed
326 +* Opt-out of sharing sensitive or restricted content
327 +
328 +=== FR20 – Synchronization & Conflict Handling ===
329 +
330 +* Changes from remote nodes must be mergeable or explicitly conflict-marked
331 +* Conflicting verdicts are allowed and visible; not forced into consensus
332 +
333 +=== FR21 – Federation Discovery ===
334 +
335 +* Discover other nodes and their capabilities (public endpoints, policies)
336 +* Allow whitelisting / blacklisting of nodes
337 +
338 +**Basic federation** (minimum):
339 +
340 +* Subscribe to and import selected claims and scenarios from other nodes
341 +* Keep provenance (which node originated what)
342 +* Respect remote deletion / redaction notices where required by policy or law
343 +
344 +Advanced federation (later versions):
345 +
346 +* Cross-node search
347 +* Federation-wide discovery and reputation signals
348 +
349 +----
350 +
351 += Non-Functional Requirements (NFR) =
352 +
353 +== NFR1 – Transparency ==
354 +
355 +* All assumptions, evidence, and reasoning behind verdicts must be visible
356 +* AKEL involvement must be clearly labeled
357 +* Users must be able to inspect the chain of reasoning and versions
358 +
359 +== NFR2 – Security ==
360 +
361 +* Role-based access control
362 +* Transport-level security (HTTPS)
363 +* Secure storage of secrets (API keys, credentials)
364 +* Audit trails for sensitive actions
365 +
366 +== NFR3 – Privacy & Compliance ==
367 +
368 +* Configurable data retention policies
369 +* Ability to redact or pseudonymize personal data when required
370 +* Compliance hooks for jurisdiction-specific rules (e.g. GDPR-like deletion requests)
371 +
372 +== NFR4 – Performance ==
373 +
374 +* POC: typical interactions < 2 s
375 +* Release 1.0: < 300 ms for common read operations after caching
376 +* Degradation strategies under load (e.g. partial federation results, limited history)
377 +
378 +== NFR5 – Scalability ==
379 +
380 +* POC: ~50 internal testers on one node
381 +* Beta 0: ~100 external testers on one node
382 +* Release 1.0: **2000+ concurrent users** on a reasonably provisioned node
383 +
384 +Suggested technical targets for Release 1.0:
385 +
386 +* Scalable monolith or early microservice architecture
387 +* Sharded vector database (for semantic search)
388 +* Optional IPFS or other decentralized storage for large artefacts
389 +* Horizontal scalability for read capacity
390 +
391 +== NFR6 – Interoperability ==
392 +
393 +* Open, documented API
394 +* Modular AKEL that can be swapped or extended
395 +* Federation protocols that follow open standards where possible
396 +* Standard model for external integrations (e.g. news platforms, research tools)
397 +
398 +== NFR7 – Observability & Operations ==
399 +
400 +* Metrics for performance, errors, and queue backlogs
401 +* Logs for key flows (claim intake, scenario changes, verdict updates, federation sync)
402 +* Health endpoints for monitoring
403 +
404 +== NFR8 – Maintainability ==
405 +
406 +* Clear module boundaries (API, core services, AKEL, storage, federation)
407 +* Backward-compatible schema migration strategy where feasible
408 +* Configuration via files / environment variables, not hard-coded
409 +
410 +== NFR9 – Usability ==
411 +
412 +* UI optimized for **exploring complexity**, not hiding it
413 +* Support for saved views, filters, and user-level preferences
414 +* Progressive disclosure: casual users see summaries, advanced users can dive deep
415 +
416 +----
417 +
418 += Release Levels =
419 +
420 +=== Proof of Concept (POC) ===
421 +
422 +* Single node
423 +* Limited user set (~50 internal testers)
424 +* Basic claim → scenario → evidence → verdict flow
425 +* Minimal federation (optional)
426 +
427 +=== Beta 0 ===
428 +
429 +* One or few nodes
430 +* External testers (~100)
431 +* Expanded workflows and basic moderation
432 +* Initial federation experiments
433 +
434 +=== Release 1.0 ===
435 +
436 +* 2000+ concurrent users
437 +* Scalable monolith or early microservices
438 +* Sharded vector DB
439 +* IPFS optional
440 +* High automation (AKEL assistance)
441 +* Multi-node federation
442 +