Changes for page Requirements

Last modified by Robert Schaub on 2025/12/24 20:34

From 4.1 to 3.1 From 6.1 to 5.1

From version 5.1

edited by Robert Schaub
on 2025/12/12 21:13

Change comment: Rollback to version 3.1

To version 4.1

edited by Robert Schaub
on 2025/12/12 19:37

Change comment: Imported from XAR

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -1,441 +1,91 @@
  = Requirements =
--This chapter defines all functional, non-functional, user-role, and federation requirements for FactHarbor.
++This chapter defines the requirements for FactHarbor.
--It answers:
++== User Roles ==
--* Who can do what in the system?
--* What workflows must FactHarbor support?
--* What quality, transparency, and federation guarantees must be met?
++=== Reader ===
++* **Responsibilities**: Browse, search, view scenarios/verdicts, flag issues.
++* **Permissions**: Read-only access.
++* **Limitations**: Cannot change content.
------
++=== Contributor ===
++* **Responsibilities**: Submit claims, draft scenarios, attach evidence.
++* **Permissions**: Create/Edit drafts, comment.
++* **Limitations**: Cannot publish without review.
--= User Roles =
++=== Reviewer ===
++* **Responsibilities**: Validate contributions, check consistency.
++* **Permissions**: Change status to "Published" or "Rejected".
--== Reader ==
++=== Expert ===
++* **Responsibilities**: Domain-specific judgment, refine assumptions.
++* **Permissions**: Attach expert annotations, propose re-evaluation.
--Responsibilities:
++=== Moderator ===
++* **Responsibilities**: Handle abuse, spam, and manipulation.
++* **Permissions**: Hide content, ban users.
--* Browse and search claims
--* View scenarios, evidence, verdicts, and timelines
--* Compare scenarios and explore assumptions
--* Flag issues, errors, contradictions, or suspicious patterns
++=== Maintainer / Administrator ===
++* **Responsibilities**: Node config, security, role assignment.
++* **Permissions**: System configuration.
--Permissions:
++=== AKEL (AI) ===
++* **Responsibilities**: Propose drafts, normalize, classify.
++* **Permissions**: Create machine-generated drafts.
++* **Limitations**: Never publishes without human approval.
--* Read-only access to all published claims, scenarios, evidence, and verdicts
--* Use filters, search, and visualization tools (“truth landscape”, timelines, scenario comparison, etc.)
--* Create personal views (saved searches, bookmarks, etc.)
++== Functional Requirements ==
--Limitations:
++=== Claim Intake & Normalization ===
++* **FR1**: Support text, URL, document input.
++* **FR2**: Normalize wording while preserving original.
++* **FR3**: Classify by domain/type.
++* **FR4**: Cluster similar claims.
--* Cannot change shared content
--* Cannot publish new claims, scenarios, or verdicts
++=== Scenario System ===
++* **FR5**: Create scenarios linked to clusters.
++* **FR6**: Require Definitions, Assumptions, Boundaries.
++* **FR7**: Full versioning.
++* **FR8**: Side-by-side comparison.
------
++=== Evidence Management ===
++* **FR9**: Ingest external sources.
++* **FR10**: Assess reliability/quality.
++* **FR11**: Link evidence to multiple scenarios.
--== Contributor ==
++=== Verdicts & Truth Landscape ===
++* **FR12**: Likelihood-based verdicts **per scenario**.
++* **FR13**: Aggregate into Truth Landscape.
++* **FR14**: Show evolution over time.
--Responsibilities:
++=== Workflow & Audit ===
++* **FR15**: Draft -> Review -> Publish states.
++* **FR16**: Moderation tools.
++* **FR17**: Full audit trail.
--* Submit claims
--* Propose new claim clusters (if automatic clustering is insufficient)
--* Draft scenarios (definitions, assumptions, boundaries)
--* Attach evidence (sources, documents, links, datasets)
--* Suggest verdict drafts and uncertainty ranges
--* Respond to reviewer or expert feedback
++== Federation Requirements ==
--Permissions:
++* **FR18**: Node autonomy.
++* **FR19**: Configurable data sharing.
++* **FR20**: Sync with conflict handling.
++* **FR21**: Node discovery.
--* Everything a Reader can do
--* Create and edit **draft** claims, scenarios, evidence links, and verdict drafts
--* Comment on existing content and discuss assumptions
--* Propose corrections to misclassified or outdated content
++== Non-Functional Requirements ==
--Limitations:
++* **NFR1 - Transparency**: Visible reasoning and AKEL labeling.
++* **NFR2 - Security**: Role-based access, secure storage.
++* **NFR3 - Privacy**: Minimal data retention, compliance hooks.
++* **NFR4 - Performance**: < 2s response (POC).
++* **NFR5 - Scalability**: Support thousands of users (Release 1.0).
++* **NFR6 - Interoperability**: Open API.
++* **NFR7 - Observability**: Metrics and logs.
++* **NFR8 - Maintainability**: Modular architecture.
++* **NFR9 - Usability**: Progressive disclosure of complexity.
--* Cannot *publish* or mark content as “reviewed” or “approved”
--* Cannot override expert or maintainer decisions
--* Cannot change system-level settings, roles, or federation configuration
++== Release Levels ==
------
++* **POC (Fully Automated)**: Single node. **"Text to Truth Landscape"** workflow. Automated extraction, scenario generation, and verdict computation.
++* **Beta 0**: Few nodes, external testers. Expanded manual workflows and moderation.
++* **Release 1.0**: Scalable, Federated, High Automation. Multi-node federation.
--== Reviewer ==
--
--Responsibilities:
--
--* Review contributions from Contributors and AKEL drafts
--* Check internal consistency and clarity of scenarios
--* Validate that evidence is correctly linked and described
--* Ensure verdicts match the evidence and stated assumptions
--* Reject, request change, or accept content
--
--Permissions:
--
--* Everything a Contributor can do
--* Change content status from `draft` → `in review` → `published` / `rejected`
--* Send content back to Contributors with comments
--* Flag content for expert review
--
--Limitations:
--
--* Cannot modify system-wide configuration or federation topology
--* Cannot unilaterally change expert conclusions without process
--
------
--
--== Expert ==
--
--Responsibilities:
--
--* Provide domain-specific judgment on scenarios, evidence, and verdicts
--* Refine assumptions and definitions in complex or ambiguous topics
--* Identify subtle biases, missing evidence, or misinterpretations
--* Propose improved verdicts and uncertainty assessments
--
--Permissions:
--
--* Everything a Reviewer can do
--* Attach expert annotations and signed opinions to scenarios and verdicts
--* Propose re-evaluation of already published content based on new evidence
--
--Limitations:
--
--* Expert status is scoped to specific domains
--* Cannot bypass moderation, abuse policies, or legal constraints
--
------
--
--== Moderator ==
--
--Responsibilities:
--
--* Handle abuse reports, spam, harassment, and coordinated manipulation
--* Enforce community guidelines and legal constraints
--* Manage user bans, content takedowns, and visibility restrictions
--
--Permissions:
--
--* Hide or temporarily disable access to abusive content
--* Ban or restrict users in line with policy
--* Edit or redact sensitive content (e.g., doxxing, illegal material)
--
--Limitations:
--
--* Does not change factual verdicts except where required for legal / safety reasons
--* Substantive fact changes must go through the review / expert process
--
------
--
--== Maintainer / Administrator ==
--
--Responsibilities:
--
--* Maintain node configuration, security settings, and backups
--* Configure AKEL, storage, federation endpoints, and performance tuning
--* Manage role assignments (who is Reviewer, Expert, Moderator, etc.)
--* Approve software updates and schema migrations
--
--Permissions:
--
--* All read/write access to configuration, but not necessarily content editorial authority
--* Define organization-level policies (e.g., which sources are allowed by default)
--
--Limitations:
--
--* Editorial decisions on controversial topics follow governance rules, not arbitrary admin choice
--
------
--
--== AKEL (AI Knowledge Extraction Layer) ==
--
--Responsibilities:
--
--* Propose drafts — never final decisions
--* Normalize claims and extract candidate clusters
--* Draft scenarios, evidence candidates, and preliminary verdict suggestions
--* Propose re-evaluation when new evidence appears
--
--Permissions:
--
--* Create and update **machine-generated drafts** and suggestions
--* Never directly publish content without human approval
--
--Limitations:
--
--* AKEL output is always labeled as AI-generated draft
--* Must be reviewable, auditable, and overridable by humans
--
------
--
--= Functional Requirements =
--
--This section defines what the system must **do**.
--
--== Claim Intake & Normalization ==
--
--=== FR1 – Claim Intake ===
--
--The system must support Claim creation from:
--
--* Free-text input
--* URLs (web pages, articles, posts)
--* Uploaded documents and transcripts
--* Structured feeds (optional, e.g. from partner platforms)
--
--Accepted sources:
--
--* Text entered by users
--* URLs
--* Uploaded documents
--* Transcripts
--* Automated ingestion (optional federation input)
--* AKEL extraction from multi-claim texts
--
--=== FR2 – Claim Normalization ===
--
--* Convert diverse inputs into short, structured, declarative claims
--* Preserve original phrasing for reference
--* Avoid hidden reinterpretation; differences between original and normalized phrasing must be visible
--
--=== FR3 – Claim Classification ===
--
--* Classify claims by topic, domain, and type (e.g., quantitative, causal, normative)
--* Suggest which node / experts are relevant
--
--=== FR4 – Claim Clustering ===
--
--* Group similar claims into Claim Clusters
--* Allow manual correction of cluster membership
--* Provide explanation why two claims are considered “same cluster”
--
------
--
--== Scenario System ==
--
--=== FR5 – Scenario Creation ===
--
--* Contributors, Reviewers, and Experts can create scenarios
--* AKEL can propose draft scenarios
--* Each scenario is tied to exactly one Claim Cluster
--
--=== FR6 – Required Scenario Fields ===
--
--Each scenario includes:
--
--* Definitions (key terms)
--* Assumptions (explicit, testable where possible)
--* Boundaries (time, geography, population, conditions)
--* Scope of evidence considered
--* Intended decision / context (optional)
--
--=== FR7 – Scenario Versioning ===
--
--* Every change to a scenario creates a new version
--* Previous versions remain accessible with timestamps and rationale
--
--=== FR8 – Scenario Comparison ===
--
--* Users can compare scenarios side by side
--* Show differences in assumptions, definitions, and evidence sets
--
------
--
--== Evidence Management ==
--
--=== FR9 – Evidence Ingestion ===
--
--* Attach external sources (articles, studies, datasets, reports, transcripts) to Scenarios
--* Allow multiple pieces of evidence per Scenario
--
--=== FR10 – Evidence Assessment ===
--
--For each piece of evidence:
--
--* Assign reliability / quality ratings
--* Capture who rated it and why
--* Indicate known limitations, biases, or conflicts of interest
--
--=== FR11 – Evidence Linking ===
--
--* Link one piece of evidence to multiple scenarios if relevant
--* Make dependencies explicit (e.g., “Scenario A uses subset of evidence used in Scenario B”)
--
------
--
--== Verdicts & Truth Landscape ==
--
--=== FR12 – Scenario Verdicts ===
--
--For each Scenario:
--
--* Provide a **probability- or likelihood-based verdict**
--* Capture uncertainty and reasoning
--* Distinguish between AKEL draft and human-approved verdict
--
--=== FR13 – Truth Landscape ===
--
--* Aggregate all scenario-specific verdicts into a “truth landscape” for a claim
--* Make disagreements visible rather than collapsing them into a single binary result
--
--=== FR14 – Time Evolution ===
--
--* Show how verdicts and evidence evolve over time
--* Allow users to see “as of date X, what did we know?”
--
------
--
--== Workflow, Moderation & Audit ==
--
--=== FR15 – Workflow States ===
--
--* Draft → In Review → Published / Rejected
--* Separate states for Claims, Scenarios, Evidence, and Verdicts
--
--=== FR16 – Moderation & Abuse Handling ===
--
--* Allow Moderators to hide content or lock edits for abuse or legal reasons
--* Keep internal audit trail even if public view is restricted
--
--=== FR17 – Audit Trail ===
--
--* Every significant action (create, edit, publish, delete/hide) is logged with:
--  * Who did it
--  * When
--  * What changed
--  * Why (short comment, optional but recommended)
--
------
--
--= Federation Requirements =
--
--FactHarbor is designed to operate as a **federated network of nodes**.
--
--=== FR18 – Node Autonomy ===
--
--* Each node can run independently (local policies, local users, local moderation)
--* Nodes decide which other nodes to federate with
--
--=== FR19 – Data Sharing Modes ===
--
--Nodes must be able to:
--
--* Share claims and summaries only
--* Share selected claims, scenarios, and verdicts
--* Share full underlying evidence metadata where allowed
--* Opt-out of sharing sensitive or restricted content
--
--=== FR20 – Synchronization & Conflict Handling ===
--
--* Changes from remote nodes must be mergeable or explicitly conflict-marked
--* Conflicting verdicts are allowed and visible; not forced into consensus
--
--=== FR21 – Federation Discovery ===
--
--* Discover other nodes and their capabilities (public endpoints, policies)
--* Allow whitelisting / blacklisting of nodes
--
--**Basic federation** (minimum):
--
--* Subscribe to and import selected claims and scenarios from other nodes
--* Keep provenance (which node originated what)
--* Respect remote deletion / redaction notices where required by policy or law
--
--Advanced federation (later versions):
--
--* Cross-node search
--* Federation-wide discovery and reputation signals
--
------
--
--= Non-Functional Requirements (NFR) =
--
--== NFR1 – Transparency ==
--
--* All assumptions, evidence, and reasoning behind verdicts must be visible
--* AKEL involvement must be clearly labeled
--* Users must be able to inspect the chain of reasoning and versions
--
--== NFR2 – Security ==
--
--* Role-based access control
--* Transport-level security (HTTPS)
--* Secure storage of secrets (API keys, credentials)
--* Audit trails for sensitive actions
--
--== NFR3 – Privacy & Compliance ==
--
--* Configurable data retention policies
--* Ability to redact or pseudonymize personal data when required
--* Compliance hooks for jurisdiction-specific rules (e.g. GDPR-like deletion requests)
--
--== NFR4 – Performance ==
--
--* POC: typical interactions < 2 s
--* Release 1.0: < 300 ms for common read operations after caching
--* Degradation strategies under load (e.g. partial federation results, limited history)
--
--== NFR5 – Scalability ==
--
--* POC: **Fully automated text-to-truth-landscape** pipeline for validation.
--* Beta 0: ~100 external testers on one node
--* Release 1.0: **2000+ concurrent users** on a reasonably provisioned node
--
--Suggested technical targets for Release 1.0:
--
--* Scalable monolith or early microservice architecture
--* Sharded vector database (for semantic search)
--* Optional IPFS or other decentralized storage for large artefacts
--* Horizontal scalability for read capacity
--
--== NFR6 – Interoperability ==
--
--* Open, documented API
--* Modular AKEL that can be swapped or extended
--* Federation protocols that follow open standards where possible
--* Standard model for external integrations (e.g. news platforms, research tools)
--
--== NFR7 – Observability & Operations ==
--
--* Metrics for performance, errors, and queue backlogs
--* Logs for key flows (claim intake, scenario changes, verdict updates, federation sync)
--* Health endpoints for monitoring
--
--== NFR8 – Maintainability ==
--
--* Clear module boundaries (API, core services, AKEL, storage, federation)
--* Backward-compatible schema migration strategy where feasible
--* Configuration via files / environment variables, not hard-coded
--
--== NFR9 – Usability ==
--
--* UI optimized for **exploring complexity**, not hiding it
--* Support for saved views, filters, and user-level preferences
--* Progressive disclosure: casual users see summaries, advanced users can dive deep
--
------
--
--= Release Levels =
--
--=== Proof of Concept (POC) ===
--
--* **Status:** Fully Automated "Text to Truth Landscape"
--* **Focus:** Validating automated extraction, scenario generation, and verdict computation without human-in-the-loop.
--* **Goal:** Demonstrate model capability on raw text input.
--
--=== Beta 0 ===
--
--* One or few nodes
--* External testers (~100)
--* Expanded workflows and basic moderation
--* Initial federation experiments
--
--=== Release 1.0 ===
--
--* 2000+ concurrent users
--* Scalable monolith or early microservices
--* Sharded vector DB
--* IPFS optional
--* High automation (AKEL assistance)
--* Multi-node federation
--

Changes for page Requirements

Summary

Details

Applications

Navigation

Need help?