Wiki source code of Requirements
Last modified by Robert Schaub on 2025/12/24 20:30
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
1.1 | 1 | = Requirements = |
| 2 | |||
| 3 | This page defines **Roles**, **Responsibilities**, and **Rules** for contributors and users of FactHarbor. | ||
| 4 | |||
| 5 | == 1. Roles == | ||
| 6 | |||
| 7 | === 1.1 Reader === | ||
| 8 | |||
| 9 | **Who**: Anyone (no login required). | ||
| 10 | |||
| 11 | **Can**: | ||
| 12 | * Browse and search claims | ||
| 13 | * View scenarios, evidence, verdicts, and timelines | ||
| 14 | * Compare scenarios and explore assumptions | ||
| 15 | * Flag issues, errors, contradictions, or suspicious patterns | ||
| 16 | * Use filters, search, and visualization tools | ||
| 17 | * Create personal views (saved searches, bookmarks - local browser storage) | ||
| 18 | * **Submit claims automatically** by providing text to analyze - new claims are added automatically unless equal claims already exist in the system | ||
| 19 | |||
| 20 | **Cannot**: | ||
| 21 | * Modify existing content | ||
| 22 | * Access draft content | ||
| 23 | * Participate in governance decisions | ||
| 24 | |||
| 25 | **Note**: Readers can request human review of AI-generated content by flagging it. | ||
| 26 | |||
| 27 | === 1.2 Contributor === | ||
| 28 | |||
| 29 | **Who**: Registered and logged-in users (extends Reader capabilities). | ||
| 30 | |||
| 31 | **Can**: | ||
| 32 | * Everything a Reader can do | ||
| 33 | * Submit claims | ||
| 34 | * Submit evidence | ||
| 35 | * Provide feedback | ||
| 36 | * Suggest scenarios | ||
| 37 | * Flag content for review | ||
| 38 | * Request human review of AI-generated content | ||
| 39 | |||
| 40 | **Cannot**: | ||
| 41 | * Publish or mark content as "reviewed" or "approved" | ||
| 42 | * Override expert or maintainer decisions | ||
| 43 | * Directly modify AKEL or quality gate configurations | ||
| 44 | |||
| 45 | === 1.3 Reviewer === | ||
| 46 | |||
| 47 | **Who**: Trusted community members, appointed by maintainers. | ||
| 48 | |||
| 49 | **Can**: | ||
| 50 | * Review contributions from Contributors and AKEL drafts | ||
| 51 | * Validate AI-generated content (Mode 2 → Mode 3 transition) | ||
| 52 | * Edit claims, scenarios, and evidence | ||
| 53 | * Add clarifications or warnings | ||
| 54 | * Change content status: `draft` → `in review` → `published` / `rejected` | ||
| 55 | * Approve or reject **Tier B and C** content for "Human-Reviewed" status | ||
| 56 | * Flag content for expert review | ||
| 57 | * Participate in audit sampling | ||
| 58 | |||
| 59 | **Cannot**: | ||
| 60 | * Approve Tier A content for "Human-Reviewed" status (requires Expert) | ||
| 61 | * Change governance rules | ||
| 62 | * Unilaterally change expert conclusions without process | ||
| 63 | * Bypass quality gates | ||
| 64 | |||
| 65 | **Note on AI-Drafted Content**: | ||
| 66 | * Reviewers can validate AI-generated content (Mode 2) to promote it to "Human-Reviewed" (Mode 3) | ||
| 67 | * For Tier B and C, Reviewers have approval authority | ||
| 68 | * For Tier A, only Experts can grant "Human-Reviewed" status | ||
| 69 | |||
| 70 | === 1.4 Expert (Domain-Specific) === | ||
| 71 | |||
| 72 | **Who**: Subject-matter specialists in specific domains (medicine, law, science, etc.). | ||
| 73 | |||
| 74 | **Can**: | ||
| 75 | * Everything a Reviewer can do | ||
| 76 | * **Final authority** on Tier A content "Human-Reviewed" status | ||
| 77 | * Validate complex or controversial claims in their domain | ||
| 78 | * Define domain-specific quality standards | ||
| 79 | * Set reliability thresholds for domain sources | ||
| 80 | * Participate in risk tier assignment review | ||
| 81 | * Override AKEL suggestions in their domain (with documentation) | ||
| 82 | |||
| 83 | **Cannot**: | ||
| 84 | * Change platform governance policies | ||
| 85 | * Approve content outside their expertise domain | ||
| 86 | * Bypass technical quality gates (but can flag for adjustment) | ||
| 87 | |||
| 88 | **Specialization**: | ||
| 89 | * Experts are domain-specific (e.g., "Medical Expert", "Legal Expert", "Climate Science Expert") | ||
| 90 | * Cross-domain claims may require multiple expert reviews | ||
| 91 | |||
| 92 | === 1.5 Auditor === | ||
| 93 | |||
| 94 | **Who**: Reviewers or Experts assigned to sampling audit duties. | ||
| 95 | |||
| 96 | **Can**: | ||
| 97 | * Review sampled AI-generated content against quality standards | ||
| 98 | * Validate quality gate enforcement | ||
| 99 | * Identify patterns in AI errors or hallucinations | ||
| 100 | * Provide feedback for system improvement | ||
| 101 | * Flag content for immediate review if errors found | ||
| 102 | * Contribute to audit statistics and transparency reports | ||
| 103 | |||
| 104 | **Cannot**: | ||
| 105 | * Change audit sampling algorithms (maintainer responsibility) | ||
| 106 | * Bypass normal review workflows | ||
| 107 | * Audit content they personally created | ||
| 108 | |||
| 109 | **Selection**: | ||
| 110 | * Auditors selected based on domain expertise and review quality | ||
| 111 | * Rotation to prevent audit fatigue | ||
| 112 | * Stratified assignment (Tier A auditors need higher expertise) | ||
| 113 | |||
| 114 | **Audit Focus**: | ||
| 115 | * Tier A: Recommendation 30-50% sampling rate, expert auditors | ||
| 116 | * Tier B: Recommendation 10-20% sampling rate, reviewer/expert auditors | ||
| 117 | * Tier C: Recommendation 5-10% sampling rate, reviewer auditors | ||
| 118 | |||
| 119 | === 1.6 Moderator === | ||
| 120 | |||
| 121 | **Who**: Maintainers or trusted long-term contributors. | ||
| 122 | |||
| 123 | **Can**: | ||
| 124 | * All Reviewer and Expert capabilities (cross-domain) | ||
| 125 | * Manage user accounts and permissions | ||
| 126 | * Handle disputes and conflicts | ||
| 127 | * Enforce community guidelines | ||
| 128 | * Suspend or ban abusive users | ||
| 129 | * Finalize publication status for sensitive content | ||
| 130 | * Review and adjust risk tier assignments | ||
| 131 | * Oversee audit system performance | ||
| 132 | |||
| 133 | **Cannot**: | ||
| 134 | * Change core data model or architecture | ||
| 135 | * Override technical system constraints | ||
| 136 | * Make unilateral governance decisions without consensus | ||
| 137 | |||
| 138 | === 1.7 Maintainer === | ||
| 139 | |||
| 140 | **Who**: Core team members responsible for the platform. | ||
| 141 | |||
| 142 | **Can**: | ||
| 143 | * All Moderator capabilities | ||
| 144 | * Change data model, architecture, and technical systems | ||
| 145 | * Configure quality gates and AKEL parameters | ||
| 146 | * Adjust audit sampling algorithms | ||
| 147 | * Set and modify risk tier policies | ||
| 148 | * Make platform-wide governance decisions | ||
| 149 | * Access and modify backend systems | ||
| 150 | * Deploy updates and fixes | ||
| 151 | * Grant and revoke roles | ||
| 152 | |||
| 153 | **Governance**: | ||
| 154 | * Maintainers operate under organizational governance rules | ||
| 155 | * Major policy changes require Governing Team approval | ||
| 156 | * Technical decisions made collaboratively | ||
| 157 | |||
| 158 | |||
| 159 | == 2. Content Publication States == | ||
| 160 | |||
| 161 | === 2.1 Mode 1: Draft === | ||
| 162 | * Not visible to public | ||
| 163 | * Visible to contributor and reviewers | ||
| 164 | * Can be edited by contributor or reviewers | ||
| 165 | * Default state for failed quality gates | ||
| 166 | |||
| 167 | === 2.2 Mode 2: AI-Generated (Published) === | ||
| 168 | * **Public** and visible to all users | ||
| 169 | * Clearly labeled as "AI-Generated, Awaiting Human Review" | ||
| 170 | * Passed all automated quality gates | ||
| 171 | * Risk tier displayed (A/B/C) | ||
| 172 | * Users can: | ||
| |
2.1 | 173 | ** Read and use content |
| 174 | ** Request human review | ||
| 175 | ** Flag for expert attention | ||
| |
1.1 | 176 | * Subject to sampling audits |
| 177 | * Can be promoted to Mode 3 by reviewer/expert validation | ||
| 178 | |||
| 179 | === 2.3 Mode 3: Human-Reviewed (Published) === | ||
| 180 | * **Public** and visible to all users | ||
| 181 | * Labeled as "Human-Reviewed" with reviewer/expert attribution | ||
| 182 | * Passed quality gates + human validation | ||
| 183 | * Highest trust level | ||
| 184 | * For Tier A, requires Expert approval | ||
| 185 | * For Tier B/C, Reviewer approval sufficient | ||
| 186 | |||
| 187 | === 2.4 Rejected === | ||
| 188 | * Not visible to public | ||
| 189 | * Visible to contributor with rejection reason | ||
| 190 | * Can be resubmitted after addressing issues | ||
| 191 | * Rejection logged for transparency | ||
| 192 | |||
| 193 | |||
| 194 | == 3. Contribution Rules == | ||
| 195 | |||
| 196 | === 3.1 All Contributors Must: === | ||
| 197 | * Provide sources for claims | ||
| 198 | * Use clear, neutral language | ||
| 199 | * Avoid personal attacks or insults | ||
| 200 | * Respect intellectual property (cite sources) | ||
| 201 | * Accept community feedback gracefully | ||
| 202 | |||
| 203 | === 3.2 AKEL (AI) Must: === | ||
| 204 | * Mark all outputs with `AuthorType = AI` | ||
| 205 | * Pass quality gates before Mode 2 publication | ||
| 206 | * Perform mandatory contradiction search | ||
| 207 | * Disclose confidence levels and uncertainty | ||
| 208 | * Provide traceable reasoning chains | ||
| 209 | * Flag potential bubbles or echo chambers | ||
| 210 | * Submit to audit sampling | ||
| 211 | |||
| 212 | === 3.3 Reviewers Must: === | ||
| 213 | * Be impartial and evidence-based | ||
| 214 | * Document reasoning for decisions | ||
| 215 | * Escalate to experts when appropriate | ||
| 216 | * Participate in audits when assigned | ||
| 217 | * Provide constructive feedback | ||
| 218 | |||
| 219 | === 3.4 Experts Must: === | ||
| 220 | * Stay within domain expertise | ||
| 221 | * Disclose conflicts of interest | ||
| 222 | * Document specialized terminology | ||
| 223 | * Provide reasoning for domain-specific decisions | ||
| 224 | * Participate in Tier A audits | ||
| 225 | |||
| 226 | |||
| 227 | == 4. Quality Standards == | ||
| 228 | |||
| 229 | === 4.1 Source Requirements === | ||
| 230 | * Primary sources preferred over secondary | ||
| 231 | * Publication date and author must be identifiable | ||
| 232 | * Sources must be accessible (not paywalled when possible) | ||
| 233 | * Contradictory sources must be acknowledged | ||
| 234 | * Echo chamber sources must be flagged | ||
| 235 | |||
| 236 | === 4.2 Claim Requirements === | ||
| 237 | * Falsifiable or evaluable | ||
| 238 | * Clear definitions of key terms | ||
| 239 | * Boundaries and scope stated | ||
| 240 | * Assumptions made explicit | ||
| 241 | * Uncertainty acknowledged | ||
| 242 | |||
| 243 | === 4.3 Evidence Requirements === | ||
| 244 | * Relevant to the claim and scenario | ||
| 245 | * Reliability assessment provided | ||
| 246 | * Methodology described (for studies) | ||
| 247 | * Limitations noted | ||
| 248 | * Conflicting evidence acknowledged | ||
| 249 | |||
| 250 | |||
| |
2.1 | 251 | == 5. Risk tier Assignment == |
| |
1.1 | 252 | |
| 253 | **Automated (AKEL)**: Initial tier suggested based on domain, keywords, impact | ||
| 254 | **Human Validation**: Moderators or Experts can override AKEL suggestions | ||
| 255 | **Review**: Risk tiers periodically reviewed based on audit outcomes | ||
| 256 | |||
| 257 | **Tier A Indicators**: | ||
| 258 | * Medical diagnosis or treatment advice | ||
| 259 | * Legal interpretation or advice | ||
| 260 | * Election or voting information | ||
| 261 | * Safety or security sensitive | ||
| 262 | * Major financial decisions | ||
| 263 | * Potential for significant harm | ||
| 264 | |||
| 265 | **Tier B Indicators**: | ||
| 266 | * Complex scientific causality | ||
| 267 | * Contested policy domains | ||
| 268 | * Historical interpretation with political implications | ||
| 269 | * Significant economic impact claims | ||
| 270 | |||
| 271 | **Tier C Indicators**: | ||
| 272 | * Established historical facts | ||
| 273 | * Simple definitions | ||
| 274 | * Well-documented scientific consensus | ||
| 275 | * Basic reference information | ||
| 276 | |||
| 277 | |||
| 278 | == 6. User Role Hierarchy Diagram == | ||
| 279 | |||
| 280 | The following diagram visualizes the complete role hierarchy: | ||
| 281 | |||
| 282 | |||
| 283 | == 7. Role Hierarchy Diagrams == | ||
| 284 | |||
| 285 | === 7.1 User Class Diagram === | ||
| 286 | |||
| 287 | The following class diagram visualizes the complete user role hierarchy: | ||
| 288 | |||
| 289 | {{include reference="FactHarbor.Specification.Diagrams.User Class Diagram.WebHome"/}} | ||
| 290 | |||
| 291 | === 7.2 Human User Roles === | ||
| 292 | |||
| 293 | This diagram shows the two-track progression for human users: | ||
| 294 | |||
| 295 | {{include reference="FactHarbor.Specification.Diagrams.Human User Roles.WebHome"/}} | ||
| 296 | |||
| 297 | === 7.3 Technical and System Users === | ||
| 298 | |||
| 299 | This diagram shows system processes and their management: | ||
| 300 | |||
| 301 | {{include reference="FactHarbor.Specification.Diagrams.Technical and System Users.WebHome"/}} | ||
| 302 | |||
| 303 | **Key Design Principles**: | ||
| 304 | * **Two tracks from Contributor**: Content Track (Reviewer) and Technical Track (Maintainer) | ||
| 305 | * **Technical Users**: System processes (AKEL, bots) managed by Maintainers | ||
| 306 | * **Separation of concerns**: Editorial authority independent from technical authority | ||
| 307 | |||
| 308 | |||
| 309 | = Functional Requirements = | ||
| 310 | |||
| 311 | |||
| 312 | This page defines what the FactHarbor system must **do** to fulfill its mission. | ||
| 313 | |||
| 314 | Requirements are structured as FR (Functional Requirement) items and organized by capability area. | ||
| 315 | |||
| 316 | |||
| 317 | == 8. Claim Intake & Normalization == | ||
| 318 | |||
| 319 | === 8.1 FR1 – Claim Intake === | ||
| 320 | |||
| 321 | The system must support Claim creation from: | ||
| 322 | * Free-text input (from any Reader) | ||
| 323 | * URLs (web pages, articles, posts) | ||
| 324 | * Uploaded documents and transcripts | ||
| 325 | * Structured feeds (optional, e.g. from partner platforms) | ||
| 326 | * Automated ingestion (federation input) | ||
| 327 | * AKEL extraction from multi-claim texts | ||
| 328 | |||
| 329 | **Automatic submission**: Any Reader can submit text, and new claims are added automatically unless identical claims already exist. | ||
| 330 | |||
| 331 | === 8.2 FR2 – Claim Normalization === | ||
| 332 | |||
| 333 | * Convert diverse inputs into short, structured, declarative claims | ||
| 334 | * Preserve original phrasing for reference | ||
| 335 | * Avoid hidden reinterpretation; differences between original and normalized phrasing must be visible | ||
| 336 | |||
| 337 | === 8.3 FR3 – Claim Classification === | ||
| 338 | |||
| 339 | * Classify claims by topic, domain, and type (e.g., quantitative, causal, normative) | ||
| 340 | * Assign risk tier (A/B/C) based on domain and potential impact | ||
| 341 | * Suggest which node / experts are relevant | ||
| 342 | |||
| 343 | === 8.4 FR4 – Claim Clustering === | ||
| 344 | |||
| 345 | * Group similar claims into Claim Clusters | ||
| 346 | * Allow manual correction of cluster membership | ||
| 347 | * Provide explanation why two claims are considered "same cluster" | ||
| 348 | |||
| 349 | |||
| 350 | == 9. Scenario System == | ||
| 351 | |||
| 352 | === 9.1 FR5 – Scenario Creation === | ||
| 353 | |||
| 354 | * Contributors, Reviewers, and Experts can create scenarios | ||
| 355 | * AKEL can propose draft scenarios | ||
| 356 | * Each scenario is tied to exactly one Claim Cluster | ||
| 357 | |||
| 358 | === 9.2 FR6 – Required Scenario Fields === | ||
| 359 | |||
| 360 | Each scenario includes: | ||
| 361 | * Definitions (key terms) | ||
| 362 | * Assumptions (explicit, testable where possible) | ||
| 363 | * Boundaries (time, geography, population, conditions) | ||
| 364 | * Scope of evidence considered | ||
| 365 | * Intended decision / context (optional) | ||
| 366 | |||
| 367 | === 9.3 FR7 – Scenario Versioning === | ||
| 368 | |||
| 369 | * Every change to a scenario creates a new version | ||
| 370 | * Previous versions remain accessible with timestamps and rationale | ||
| 371 | * ParentVersionID links versions | ||
| 372 | |||
| 373 | === 9.4 FR8 – Scenario Comparison === | ||
| 374 | |||
| 375 | * Users can compare scenarios side by side | ||
| 376 | * Show differences in assumptions, definitions, and evidence sets | ||
| 377 | |||
| 378 | |||
| 379 | == 10. Evidence Management == | ||
| 380 | |||
| 381 | === 10.1 FR9 – Evidence Ingestion === | ||
| 382 | |||
| 383 | * Attach external sources (articles, studies, datasets, reports, transcripts) to Scenarios | ||
| 384 | * Allow multiple pieces of evidence per Scenario | ||
| 385 | * Support large file uploads (with size limits) | ||
| 386 | |||
| 387 | === 10.2 FR10 – Evidence Assessment === | ||
| 388 | |||
| 389 | For each piece of evidence: | ||
| 390 | * Assign reliability / quality ratings | ||
| 391 | * Capture who rated it and why | ||
| 392 | * Indicate known limitations, biases, or conflicts of interest | ||
| 393 | * Track evidence version history | ||
| 394 | |||
| 395 | === 10.3 FR11 – Evidence Linking === | ||
| 396 | |||
| 397 | * Link one piece of evidence to multiple scenarios if relevant | ||
| 398 | * Make dependencies explicit (e.g., "Scenario A uses subset of evidence used in Scenario B") | ||
| 399 | * Use ScenarioEvidenceLink table with RelevanceScore | ||
| 400 | |||
| 401 | |||
| 402 | == 11. Verdicts & Truth Landscape == | ||
| 403 | |||
| 404 | === 11.1 FR12 – Scenario Verdicts === | ||
| 405 | |||
| 406 | For each Scenario: | ||
| 407 | * Provide a **probability- or likelihood-based verdict** | ||
| 408 | * Capture uncertainty and reasoning | ||
| 409 | * Distinguish between AKEL draft and human-approved verdict | ||
| 410 | * Support Mode 1 (draft), Mode 2 (AI-generated), Mode 3 (human-reviewed) | ||
| 411 | |||
| 412 | === 11.2 FR13 – Truth Landscape === | ||
| 413 | |||
| 414 | * Aggregate all scenario-specific verdicts into a "truth landscape" for a claim | ||
| 415 | * Make disagreements visible rather than collapsing them into a single binary result | ||
| 416 | * Show parallel scenarios and their respective verdicts | ||
| 417 | |||
| 418 | === 11.3 FR14 – Time Evolution === | ||
| 419 | |||
| 420 | * Show how verdicts and evidence evolve over time | ||
| 421 | * Allow users to see "as of date X, what did we know?" | ||
| 422 | * Maintain complete version history for auditing | ||
| 423 | |||
| 424 | |||
| 425 | == 12. Workflow, Moderation & Audit == | ||
| 426 | |||
| 427 | === 12.1 FR15 – Workflow States === | ||
| 428 | |||
| 429 | * Draft → In Review → Published / Rejected | ||
| 430 | * Separate states for Claims, Scenarios, Evidence, and Verdicts | ||
| 431 | * Support Mode 1/2/3 publication model | ||
| 432 | |||
| 433 | === 12.2 FR16 – Moderation & Abuse Handling === | ||
| 434 | |||
| 435 | * Allow Moderators to hide content or lock edits for abuse or legal reasons | ||
| 436 | * Keep internal audit trail even if public view is restricted | ||
| 437 | * Support user reporting and flagging | ||
| 438 | |||
| 439 | === 12.3 FR17 – Audit Trail === | ||
| 440 | |||
| 441 | * Every significant action (create, edit, publish, delete/hide) is logged with: | ||
| |
2.1 | 442 | ** Who did it |
| 443 | ** When (timestamp) | ||
| 444 | ** What changed (diffs) | ||
| 445 | ** Why (justification text) | ||
| |
1.1 | 446 | |
| 447 | |||
| 448 | == 13. Quality Gates & AI Review == | ||
| 449 | |||
| 450 | === 13.1 FR18 – Quality Gate Validation === | ||
| 451 | |||
| 452 | Before AI-generated content (Mode 2) publication, enforce: | ||
| 453 | * Gate 1: Source Quality | ||
| 454 | * Gate 2: Contradiction Search (MANDATORY) | ||
| 455 | * Gate 3: Uncertainty Quantification | ||
| 456 | * Gate 4: Structural Integrity | ||
| 457 | |||
| 458 | === 13.2 FR19 – Audit Sampling === | ||
| 459 | |||
| 460 | * Implement stratified sampling by risk tier | ||
| 461 | * Recommendation: 30-50% Tier A, 10-20% Tier B, 5-10% Tier C | ||
| 462 | * Support audit workflow and feedback loop | ||
| 463 | |||
| 464 | === 13.3 FR20 – Risk Tier Assignment === | ||
| 465 | |||
| 466 | * AKEL suggests tier based on domain, keywords, impact | ||
| 467 | * Moderators and Experts can override | ||
| 468 | * Risk tier affects publication workflow | ||
| 469 | |||
| 470 | |||
| 471 | == 14. Federation Requirements == | ||
| 472 | |||
| 473 | === 14.1 FR21 – Node Autonomy === | ||
| 474 | |||
| 475 | * Each node can run independently (local policies, local users, local moderation) | ||
| 476 | * Nodes decide which other nodes to federate with | ||
| 477 | * Trust levels: Trusted / Neutral / Untrusted | ||
| 478 | |||
| 479 | === 14.2 FR22 – Data Sharing Modes === | ||
| 480 | |||
| 481 | Nodes must be able to: | ||
| 482 | * Share claims and summaries only | ||
| 483 | * Share selected claims, scenarios, and verdicts | ||
| 484 | * Share full underlying evidence metadata where allowed | ||
| 485 | * Opt-out of sharing sensitive or restricted content | ||
| 486 | |||
| 487 | === 14.3 FR23 – Synchronization & Conflict Handling === | ||
| 488 | |||
| 489 | * Changes from remote nodes must be mergeable or explicitly conflict-marked | ||
| 490 | * Conflicting verdicts are allowed and visible; not forced into consensus | ||
| 491 | * Support push/pull/subscription synchronization | ||
| 492 | |||
| 493 | === 14.4 FR24 – Federation Discovery === | ||
| 494 | |||
| 495 | * Discover other nodes and their capabilities (public endpoints, policies) | ||
| 496 | * Allow whitelisting / blacklisting of nodes | ||
| 497 | * Global identifier format: `factharbor://node_url/type/local_id` | ||
| 498 | |||
| 499 | === 14.5 FR25 – Cross-Node AI Knowledge Exchange === | ||
| 500 | |||
| 501 | * Share vector embeddings for clustering | ||
| 502 | * Share canonical claim forms | ||
| 503 | * Share scenario templates | ||
| 504 | * Share contradiction alerts | ||
| 505 | * NEVER share model weights | ||
| 506 | * NEVER override local governance | ||
| 507 | |||
| 508 | |||
| 509 | == 15. Non-Functional Requirements == | ||
| 510 | |||
| 511 | === 15.1 NFR1 – Transparency === | ||
| 512 | |||
| 513 | * All assumptions, evidence, and reasoning behind verdicts must be visible | ||
| 514 | * AKEL involvement must be clearly labeled | ||
| 515 | * Users must be able to inspect the chain of reasoning and versions | ||
| 516 | |||
| 517 | === 15.2 NFR2 – Security === | ||
| 518 | |||
| 519 | * Role-based access control | ||
| 520 | * Transport-level security (HTTPS) | ||
| 521 | * Secure storage of secrets (API keys, credentials) | ||
| 522 | * Audit trails for sensitive actions | ||
| 523 | |||
| 524 | === 15.3 NFR3 – Privacy & Compliance === | ||
| 525 | |||
| 526 | * Configurable data retention policies | ||
| 527 | * Ability to redact or pseudonymize personal data when required | ||
| 528 | * Compliance hooks for jurisdiction-specific rules (e.g. GDPR-like deletion requests) | ||
| 529 | |||
| 530 | === 15.4 NFR4 – Performance === | ||
| 531 | |||
| 532 | * POC: typical interactions < 2 s | ||
| 533 | * Release 1.0: < 300 ms for common read operations after caching | ||
| 534 | * Degradation strategies under load | ||
| 535 | |||
| 536 | === 15.5 NFR5 – Scalability === | ||
| 537 | |||
| 538 | * POC: 50 internal testers on one node | ||
| 539 | * Beta 0: 100 external testers on one node | ||
| 540 | * Release 1.0: **2000+ concurrent users** on a reasonably provisioned node | ||
| 541 | |||
| 542 | Technical targets for Release 1.0: | ||
| 543 | * Scalable monolith or early microservice architecture | ||
| 544 | * Sharded vector database (for semantic search) | ||
| 545 | * Optional IPFS or other decentralized storage for large artifacts | ||
| 546 | * Horizontal scalability for read capacity | ||
| 547 | |||
| 548 | === 15.6 NFR6 – Interoperability === | ||
| 549 | |||
| 550 | * Open, documented API | ||
| 551 | * Modular AKEL that can be swapped or extended | ||
| 552 | * Federation protocols that follow open standards where possible | ||
| 553 | * Standard model for external integrations | ||
| 554 | |||
| 555 | === 15.7 NFR7 – Observability & Operations === | ||
| 556 | |||
| 557 | * Metrics for performance, errors, and queue backlogs | ||
| 558 | * Logs for key flows (claim intake, scenario changes, verdict updates, federation sync) | ||
| 559 | * Health endpoints for monitoring | ||
| 560 | |||
| 561 | === 15.8 NFR8 – Maintainability === | ||
| 562 | |||
| 563 | * Clear module boundaries (API, core services, AKEL, storage, federation) | ||
| 564 | * Backward-compatible schema migration strategy where feasible | ||
| 565 | * Configuration via files / environment variables, not hard-coded | ||
| 566 | |||
| 567 | === 15.9 NFR9 – Usability === | ||
| 568 | |||
| 569 | * UI optimized for **exploring complexity**, not hiding it | ||
| 570 | * Support for saved views, filters, and user-level preferences | ||
| 571 | * Progressive disclosure: casual users see summaries, advanced users can dive deep | ||
| 572 | |||
| 573 | |||
| 574 | == 16. Release Levels == | ||
| 575 | |||
| 576 | === 16.1 Proof of Concept (POC) === | ||
| 577 | |||
| 578 | * Single node | ||
| 579 | * Limited user set (50 internal testers) | ||
| 580 | * Basic claim → scenario → evidence → verdict flow | ||
| 581 | * Minimal federation (optional) | ||
| 582 | * AI-generated publication (Mode 2) demonstration | ||
| 583 | * Quality gates active | ||
| 584 | |||
| 585 | === 16.2 Beta 0 === | ||
| 586 | |||
| 587 | * One or few nodes | ||
| 588 | * External testers (100) | ||
| 589 | * Expanded workflows and basic moderation | ||
| 590 | * Initial federation experiments | ||
| 591 | * Audit sampling implemented | ||
| 592 | |||
| 593 | === 16.3 Release 1.0 === | ||
| 594 | |||
| 595 | * 2000+ concurrent users | ||
| 596 | * Scalable architecture | ||
| 597 | * Sharded vector DB | ||
| 598 | * IPFS optional | ||
| 599 | * High automation (AKEL assistance) | ||
| 600 | * Multi-node federation with full sync protocol | ||
| 601 | * Mature audit system | ||
| 602 | |||
| 603 | |||
| 604 | == 17. Related Pages == | ||
| 605 | |||
| 606 | |||
| 607 | * [[AKEL (AI Knowledge Extraction Layer)>>FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] | ||
| 608 | * [[Automation>>FactHarbor.Specification.Automation.WebHome]] | ||
| 609 | * [[Workflows>>FactHarbor.Specification.Workflows.WebHome]] | ||
| 610 | * [[Governance>>FactHarbor.Organisation.Governance]] | ||
| 611 |