Changes for page Requirements
Last modified by Robert Schaub on 2025/12/24 20:34
Summary
-
Page properties (1 modified, 0 added, 0 removed)
Details
- Page properties
-
- Content
-
... ... @@ -4,11 +4,32 @@ 4 4 5 5 == Roles == 6 6 7 +=== 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 + 7 7 === Contributor === 8 8 9 -**Who**: Anyone(loggedoranonymous).29 +**Who**: Registered and logged-in users (extends Reader capabilities). 10 10 11 11 **Can**: 32 +* Everything a Reader can do 12 12 * Submit claims 13 13 * Submit evidence 14 14 * Provide feedback ... ... @@ -259,8 +259,362 @@ 259 259 260 260 ---- 261 261 283 + 284 +---- 285 + 286 +== User Role Hierarchy Diagram == 287 + 288 +The following diagram visualizes the complete role hierarchy: 289 + 290 +{{include reference="Test.FactHarborV09.Specification.Diagrams.User Class Diagram.WebHome"/}} 291 + 292 +---- 293 + 294 +---- 295 + 296 +== Role Hierarchy Diagrams == 297 + 298 +=== User Class Diagram === 299 + 300 +The following class diagram visualizes the complete user role hierarchy: 301 + 302 +{{include reference="Test.FactHarborV09.Specification.Diagrams.User Class Diagram.WebHome"/}} 303 + 304 +=== Human User Roles === 305 + 306 +This diagram shows the two-track progression for human users: 307 + 308 +{{include reference="Test.FactHarborV09.Specification.Diagrams.Human User Roles.WebHome"/}} 309 + 310 +=== Technical and System Users === 311 + 312 +This diagram shows system processes and their management: 313 + 314 +{{include reference="Test.FactHarborV09.Specification.Diagrams.Technical and System Users.WebHome"/}} 315 + 316 +**Key Design Principles**: 317 +* **Two tracks from Contributor**: Content Track (Reviewer) and Technical Track (Maintainer) 318 +* **Technical Users**: System processes (AKEL, bots) managed by Maintainers 319 +* **Separation of concerns**: Editorial authority independent from technical authority 320 + 321 +---- 322 + 323 + 324 + 325 +---- 326 + 327 += Functional Requirements = 328 + 329 + 330 + 331 +This page defines what the FactHarbor system must **do** to fulfill its mission. 332 + 333 +Requirements are structured as FR (Functional Requirement) items and organized by capability area. 334 + 335 +--- 336 + 337 +== Claim Intake & Normalization == 338 + 339 +=== FR1 – Claim Intake === 340 + 341 +The system must support Claim creation from: 342 +* Free-text input (from any Reader) 343 +* URLs (web pages, articles, posts) 344 +* Uploaded documents and transcripts 345 +* Structured feeds (optional, e.g. from partner platforms) 346 +* Automated ingestion (federation input) 347 +* AKEL extraction from multi-claim texts 348 + 349 +**Automatic submission**: Any Reader can submit text, and new claims are added automatically unless identical claims already exist. 350 + 351 +=== FR2 – Claim Normalization === 352 + 353 +* Convert diverse inputs into short, structured, declarative claims 354 +* Preserve original phrasing for reference 355 +* Avoid hidden reinterpretation; differences between original and normalized phrasing must be visible 356 + 357 +=== FR3 – Claim Classification === 358 + 359 +* Classify claims by topic, domain, and type (e.g., quantitative, causal, normative) 360 +* Assign risk tier (A/B/C) based on domain and potential impact 361 +* Suggest which node / experts are relevant 362 + 363 +=== FR4 – Claim Clustering === 364 + 365 +* Group similar claims into Claim Clusters 366 +* Allow manual correction of cluster membership 367 +* Provide explanation why two claims are considered "same cluster" 368 + 369 +--- 370 + 371 +== Scenario System == 372 + 373 +=== FR5 – Scenario Creation === 374 + 375 +* Contributors, Reviewers, and Experts can create scenarios 376 +* AKEL can propose draft scenarios 377 +* Each scenario is tied to exactly one Claim Cluster 378 + 379 +=== FR6 – Required Scenario Fields === 380 + 381 +Each scenario includes: 382 +* Definitions (key terms) 383 +* Assumptions (explicit, testable where possible) 384 +* Boundaries (time, geography, population, conditions) 385 +* Scope of evidence considered 386 +* Intended decision / context (optional) 387 + 388 +=== FR7 – Scenario Versioning === 389 + 390 +* Every change to a scenario creates a new version 391 +* Previous versions remain accessible with timestamps and rationale 392 +* ParentVersionID links versions 393 + 394 +=== FR8 – Scenario Comparison === 395 + 396 +* Users can compare scenarios side by side 397 +* Show differences in assumptions, definitions, and evidence sets 398 + 399 +--- 400 + 401 +== Evidence Management == 402 + 403 +=== FR9 – Evidence Ingestion === 404 + 405 +* Attach external sources (articles, studies, datasets, reports, transcripts) to Scenarios 406 +* Allow multiple pieces of evidence per Scenario 407 +* Support large file uploads (with size limits) 408 + 409 +=== FR10 – Evidence Assessment === 410 + 411 +For each piece of evidence: 412 +* Assign reliability / quality ratings 413 +* Capture who rated it and why 414 +* Indicate known limitations, biases, or conflicts of interest 415 +* Track evidence version history 416 + 417 +=== FR11 – Evidence Linking === 418 + 419 +* Link one piece of evidence to multiple scenarios if relevant 420 +* Make dependencies explicit (e.g., "Scenario A uses subset of evidence used in Scenario B") 421 +* Use ScenarioEvidenceLink table with RelevanceScore 422 + 423 +--- 424 + 425 +== Verdicts & Truth Landscape == 426 + 427 +=== FR12 – Scenario Verdicts === 428 + 429 +For each Scenario: 430 +* Provide a **probability- or likelihood-based verdict** 431 +* Capture uncertainty and reasoning 432 +* Distinguish between AKEL draft and human-approved verdict 433 +* Support Mode 1 (draft), Mode 2 (AI-generated), Mode 3 (human-reviewed) 434 + 435 +=== FR13 – Truth Landscape === 436 + 437 +* Aggregate all scenario-specific verdicts into a "truth landscape" for a claim 438 +* Make disagreements visible rather than collapsing them into a single binary result 439 +* Show parallel scenarios and their respective verdicts 440 + 441 +=== FR14 – Time Evolution === 442 + 443 +* Show how verdicts and evidence evolve over time 444 +* Allow users to see "as of date X, what did we know?" 445 +* Maintain complete version history for auditing 446 + 447 +--- 448 + 449 +== Workflow, Moderation & Audit == 450 + 451 +=== FR15 – Workflow States === 452 + 453 +* Draft → In Review → Published / Rejected 454 +* Separate states for Claims, Scenarios, Evidence, and Verdicts 455 +* Support Mode 1/2/3 publication model 456 + 457 +=== FR16 – Moderation & Abuse Handling === 458 + 459 +* Allow Moderators to hide content or lock edits for abuse or legal reasons 460 +* Keep internal audit trail even if public view is restricted 461 +* Support user reporting and flagging 462 + 463 +=== FR17 – Audit Trail === 464 + 465 +* Every significant action (create, edit, publish, delete/hide) is logged with: 466 + ** Who did it 467 + ** When (timestamp) 468 + ** What changed (diffs) 469 + ** Why (justification text) 470 + 471 +--- 472 + 473 +== Quality Gates & AI Review == 474 + 475 +=== FR18 – Quality Gate Validation === 476 + 477 +Before AI-generated content (Mode 2) publication, enforce: 478 +* Gate 1: Source Quality 479 +* Gate 2: Contradiction Search (MANDATORY) 480 +* Gate 3: Uncertainty Quantification 481 +* Gate 4: Structural Integrity 482 + 483 +=== FR19 – Audit Sampling === 484 + 485 +* Implement stratified sampling by risk tier 486 +* Recommendation: 30-50% Tier A, 10-20% Tier B, 5-10% Tier C 487 +* Support audit workflow and feedback loop 488 + 489 +=== FR20 – Risk Tier Assignment === 490 + 491 +* AKEL suggests tier based on domain, keywords, impact 492 +* Moderators and Experts can override 493 +* Risk tier affects publication workflow 494 + 495 +--- 496 + 497 +== Federation Requirements == 498 + 499 +=== FR21 – Node Autonomy === 500 + 501 +* Each node can run independently (local policies, local users, local moderation) 502 +* Nodes decide which other nodes to federate with 503 +* Trust levels: Trusted / Neutral / Untrusted 504 + 505 +=== FR22 – Data Sharing Modes === 506 + 507 +Nodes must be able to: 508 +* Share claims and summaries only 509 +* Share selected claims, scenarios, and verdicts 510 +* Share full underlying evidence metadata where allowed 511 +* Opt-out of sharing sensitive or restricted content 512 + 513 +=== FR23 – Synchronization & Conflict Handling === 514 + 515 +* Changes from remote nodes must be mergeable or explicitly conflict-marked 516 +* Conflicting verdicts are allowed and visible; not forced into consensus 517 +* Support push/pull/subscription synchronization 518 + 519 +=== FR24 – Federation Discovery === 520 + 521 +* Discover other nodes and their capabilities (public endpoints, policies) 522 +* Allow whitelisting / blacklisting of nodes 523 +* Global identifier format: `factharbor://node_url/type/local_id` 524 + 525 +=== FR25 – Cross-Node AI Knowledge Exchange === 526 + 527 +* Share vector embeddings for clustering 528 +* Share canonical claim forms 529 +* Share scenario templates 530 +* Share contradiction alerts 531 +* NEVER share model weights 532 +* NEVER override local governance 533 + 534 +--- 535 + 536 +== Non-Functional Requirements == 537 + 538 +=== NFR1 – Transparency === 539 + 540 +* All assumptions, evidence, and reasoning behind verdicts must be visible 541 +* AKEL involvement must be clearly labeled 542 +* Users must be able to inspect the chain of reasoning and versions 543 + 544 +=== NFR2 – Security === 545 + 546 +* Role-based access control 547 +* Transport-level security (HTTPS) 548 +* Secure storage of secrets (API keys, credentials) 549 +* Audit trails for sensitive actions 550 + 551 +=== NFR3 – Privacy & Compliance === 552 + 553 +* Configurable data retention policies 554 +* Ability to redact or pseudonymize personal data when required 555 +* Compliance hooks for jurisdiction-specific rules (e.g. GDPR-like deletion requests) 556 + 557 +=== NFR4 – Performance === 558 + 559 +* POC: typical interactions < 2 s 560 +* Release 1.0: < 300 ms for common read operations after caching 561 +* Degradation strategies under load 562 + 563 +=== NFR5 – Scalability === 564 + 565 +* POC: 50 internal testers on one node 566 +* Beta 0: 100 external testers on one node 567 +* Release 1.0: **2000+ concurrent users** on a reasonably provisioned node 568 + 569 +Technical targets for Release 1.0: 570 +* Scalable monolith or early microservice architecture 571 +* Sharded vector database (for semantic search) 572 +* Optional IPFS or other decentralized storage for large artifacts 573 +* Horizontal scalability for read capacity 574 + 575 +=== NFR6 – Interoperability === 576 + 577 +* Open, documented API 578 +* Modular AKEL that can be swapped or extended 579 +* Federation protocols that follow open standards where possible 580 +* Standard model for external integrations 581 + 582 +=== NFR7 – Observability & Operations === 583 + 584 +* Metrics for performance, errors, and queue backlogs 585 +* Logs for key flows (claim intake, scenario changes, verdict updates, federation sync) 586 +* Health endpoints for monitoring 587 + 588 +=== NFR8 – Maintainability === 589 + 590 +* Clear module boundaries (API, core services, AKEL, storage, federation) 591 +* Backward-compatible schema migration strategy where feasible 592 +* Configuration via files / environment variables, not hard-coded 593 + 594 +=== NFR9 – Usability === 595 + 596 +* UI optimized for **exploring complexity**, not hiding it 597 +* Support for saved views, filters, and user-level preferences 598 +* Progressive disclosure: casual users see summaries, advanced users can dive deep 599 + 600 +--- 601 + 602 +== Release Levels == 603 + 604 +=== Proof of Concept (POC) === 605 + 606 +* Single node 607 +* Limited user set (50 internal testers) 608 +* Basic claim → scenario → evidence → verdict flow 609 +* Minimal federation (optional) 610 +* AI-generated publication (Mode 2) demonstration 611 +* Quality gates active 612 + 613 +=== Beta 0 === 614 + 615 +* One or few nodes 616 +* External testers (100) 617 +* Expanded workflows and basic moderation 618 +* Initial federation experiments 619 +* Audit sampling implemented 620 + 621 +=== Release 1.0 === 622 + 623 +* 2000+ concurrent users 624 +* Scalable architecture 625 +* Sharded vector DB 626 +* IPFS optional 627 +* High automation (AKEL assistance) 628 +* Multi-node federation with full sync protocol 629 +* Mature audit system 630 + 631 +--- 632 + 633 + 634 + 262 262 == Related Pages == 263 263 637 + 638 + 264 264 * [[AKEL (AI Knowledge Extraction Layer)>>FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]] 265 265 * [[Automation>>FactHarbor.Specification.Automation.WebHome]] 266 266 * [[Workflows>>FactHarbor.Specification.Workflows.WebHome]]