From c8b31b1b3099c75149918922f70acac23e950ba8 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:27:53 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ARCHITECTURE.adoc | 48 ++ ARCHITECTURE.md | 47 -- CHANGELOG.adoc | 71 +++ CHANGELOG.md | 67 --- CODE_OF_CONDUCT.adoc | 132 +++++ CODE_OF_CONDUCT.md | 128 ----- CONTRIBUTING.adoc | 111 ++++ CONTRIBUTING.md | 116 ----- GOVERNANCE.adoc | 60 +++ GOVERNANCE.md | 60 --- PROOF-NEEDS.adoc | 12 + PROOF-NEEDS.md | 10 - SECURITY.adoc | 378 ++++++++++++++ SECURITY.md | 328 ------------ TEST-NEEDS.adoc | 113 ++++ TEST-NEEDS.md | 84 --- TOPOLOGY.md => TOPOLOGY.adoc | 39 +- .../ABI-FFI-README.adoc | 240 +++++---- algorithm-shield/ARCHITECTURE.adoc | 484 ++++++++++++++++++ algorithm-shield/ARCHITECTURE.md | 464 ----------------- algorithm-shield/CODE_OF_CONDUCT.adoc | 340 ++++++++++++ algorithm-shield/CODE_OF_CONDUCT.md | 327 ------------ algorithm-shield/CONTRIBUTING.adoc | 241 +++------ algorithm-shield/CONTRIBUTING.md | 116 ----- algorithm-shield/SECURITY.adoc | 70 +++ algorithm-shield/SECURITY.md | 59 --- algorithm-shield/docs/SEAM-SUMMARY.adoc | 167 ++++++ algorithm-shield/docs/SEAM-SUMMARY.md | 141 ----- ...MMARY-20260124-SECURITY-ACCESSIBILITY.adoc | 476 +++++++++++++++++ ...SUMMARY-20260124-SECURITY-ACCESSIBILITY.md | 473 ----------------- .../docs/TEST-RESULTS-2026-01-24.adoc | 177 +++++++ .../docs/TEST-RESULTS-2026-01-24.md | 164 ------ algorithm-shield/docs/TESTING-CHECKLIST.adoc | 263 ++++++++++ algorithm-shield/docs/TESTING-CHECKLIST.md | 244 --------- .../ABI-FFI-README.adoc | 240 +++++---- defensive-multiplicity/CODE_OF_CONDUCT.adoc | 24 + defensive-multiplicity/CODE_OF_CONDUCT.md | 27 - defensive-multiplicity/CONTRIBUTING.adoc | 117 ++++- defensive-multiplicity/CONTRIBUTING.md | 116 ----- defensive-multiplicity/ETHICS_CHARTER.adoc | 97 ++++ defensive-multiplicity/ETHICS_CHARTER.md | 79 --- defensive-multiplicity/README.adoc | 123 ++--- defensive-multiplicity/README.md | 57 --- defensive-multiplicity/SECURITY.adoc | 81 +++ defensive-multiplicity/SECURITY.md | 72 --- .../ABI-FFI-README.adoc | 240 +++++---- disinfo-nesy-detector/CODE_OF_CONDUCT.adoc | 24 + disinfo-nesy-detector/CODE_OF_CONDUCT.md | 27 - disinfo-nesy-detector/CONTRIBUTING.adoc | 117 ++++- disinfo-nesy-detector/CONTRIBUTING.md | 116 ----- .../RUST_CONVERSION_NEEDED.adoc | 38 ++ .../RUST_CONVERSION_NEEDED.md | 32 -- disinfo-nesy-detector/SECURITY.adoc | 24 + disinfo-nesy-detector/SECURITY.md | 25 - .../docs/architecture/README.adoc | 19 + .../docs/architecture/README.md | 16 - docs/reports/audit/audit-2026-04-15-pre.adoc | 15 + docs/reports/audit/audit-2026-04-15-pre.md | 13 - docs/tech-debt-2026-05-26.adoc | 71 +++ docs/tech-debt-2026-05-26.md | 57 --- llm-warmup-dev.adoc | 19 + llm-warmup-dev.md | 16 - llm-warmup-user.adoc | 19 + llm-warmup-user.md | 16 - 64 files changed, 4068 insertions(+), 4119 deletions(-) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.adoc delete mode 100644 GOVERNANCE.md create mode 100644 PROOF-NEEDS.adoc delete mode 100644 PROOF-NEEDS.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (87%) rename defensive-multiplicity/ABI-FFI-README.md => algorithm-shield/ABI-FFI-README.adoc (74%) create mode 100644 algorithm-shield/ARCHITECTURE.adoc delete mode 100644 algorithm-shield/ARCHITECTURE.md create mode 100644 algorithm-shield/CODE_OF_CONDUCT.adoc delete mode 100644 algorithm-shield/CODE_OF_CONDUCT.md delete mode 100644 algorithm-shield/CONTRIBUTING.md create mode 100644 algorithm-shield/SECURITY.adoc delete mode 100644 algorithm-shield/SECURITY.md create mode 100644 algorithm-shield/docs/SEAM-SUMMARY.adoc delete mode 100644 algorithm-shield/docs/SEAM-SUMMARY.md create mode 100644 algorithm-shield/docs/SESSION-SUMMARY-20260124-SECURITY-ACCESSIBILITY.adoc delete mode 100644 algorithm-shield/docs/SESSION-SUMMARY-20260124-SECURITY-ACCESSIBILITY.md create mode 100644 algorithm-shield/docs/TEST-RESULTS-2026-01-24.adoc delete mode 100644 algorithm-shield/docs/TEST-RESULTS-2026-01-24.md create mode 100644 algorithm-shield/docs/TESTING-CHECKLIST.adoc delete mode 100644 algorithm-shield/docs/TESTING-CHECKLIST.md rename disinfo-nesy-detector/ABI-FFI-README.md => defensive-multiplicity/ABI-FFI-README.adoc (74%) create mode 100644 defensive-multiplicity/CODE_OF_CONDUCT.adoc delete mode 100644 defensive-multiplicity/CODE_OF_CONDUCT.md delete mode 100644 defensive-multiplicity/CONTRIBUTING.md create mode 100644 defensive-multiplicity/ETHICS_CHARTER.adoc delete mode 100644 defensive-multiplicity/ETHICS_CHARTER.md delete mode 100644 defensive-multiplicity/README.md create mode 100644 defensive-multiplicity/SECURITY.adoc delete mode 100644 defensive-multiplicity/SECURITY.md rename algorithm-shield/ABI-FFI-README.md => disinfo-nesy-detector/ABI-FFI-README.adoc (74%) create mode 100644 disinfo-nesy-detector/CODE_OF_CONDUCT.adoc delete mode 100644 disinfo-nesy-detector/CODE_OF_CONDUCT.md delete mode 100644 disinfo-nesy-detector/CONTRIBUTING.md create mode 100644 disinfo-nesy-detector/RUST_CONVERSION_NEEDED.adoc delete mode 100644 disinfo-nesy-detector/RUST_CONVERSION_NEEDED.md create mode 100644 disinfo-nesy-detector/SECURITY.adoc delete mode 100644 disinfo-nesy-detector/SECURITY.md create mode 100644 disinfo-nesy-detector/docs/architecture/README.adoc delete mode 100644 disinfo-nesy-detector/docs/architecture/README.md create mode 100644 docs/reports/audit/audit-2026-04-15-pre.adoc delete mode 100644 docs/reports/audit/audit-2026-04-15-pre.md create mode 100644 docs/tech-debt-2026-05-26.adoc delete mode 100644 docs/tech-debt-2026-05-26.md create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..52d5eca --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,71 @@ +== Changelog + +All notable changes to `+misinformation-defence-platform+` will be +documented in this file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: add stapeln.toml container definition +* feat: deploy UX Manifesto infrastructure +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat: adopt contractile system +* feat: add AI Gatekeeper Protocol manifest + +==== Fixed + +* fix(ci): pin upload-artifact to valid SHA in hypatia-scan.yml (Refs +standards#48) (#30) +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#29) +* fix(ci): sync hypatia-scan.yml to canonical (#28) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): adopt canonical hypatia-scan.yml (#27) +* fix(ci): Phase-2 fleet submission must not fail the security gate +(#26) +* fix(ci): hypatia-scan workdir ($\{\{ env.HOME }} resolves empty) (#25) +* fix(ci): bump erlef/setup-beam SHA for ubuntu24 runner support (#23) +* fix(deps): force-bump vulnerable transitive crates via +[patch.crates-io] (#21) +* fix(security): update dependencies to fix vulnerabilities + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs(governance): CRG v2.0 STRICT audit — C (declared) -> D (honest) +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add CRG Grade C header to TEST-NEEDS.md +* docs: add EXPLAINME.adoc — prove-it file backing README claims + +==== CI + +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#32) +* ci: bump actions/upload-artifact SHA to current v4 (#22) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci: deploy dogfood-gate, fix hypatia-scan, add pre-commit hooks + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 3119694..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,67 +0,0 @@ - - -# Changelog - -All notable changes to `misinformation-defence-platform` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: add stapeln.toml container definition -- feat: deploy UX Manifesto infrastructure -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat: adopt contractile system -- feat: add AI Gatekeeper Protocol manifest - -### Fixed - -- fix(ci): pin upload-artifact to valid SHA in hypatia-scan.yml (Refs standards#48) (#30) -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#29) -- fix(ci): sync hypatia-scan.yml to canonical (#28) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): adopt canonical hypatia-scan.yml (#27) -- fix(ci): Phase-2 fleet submission must not fail the security gate (#26) -- fix(ci): hypatia-scan workdir (${{ env.HOME }} resolves empty) (#25) -- fix(ci): bump erlef/setup-beam SHA for ubuntu24 runner support (#23) -- fix(deps): force-bump vulnerable transitive crates via [patch.crates-io] (#21) -- fix(security): update dependencies to fix vulnerabilities - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs(governance): CRG v2.0 STRICT audit — C (declared) -> D (honest) -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add CRG Grade C header to TEST-NEEDS.md -- docs: add EXPLAINME.adoc — prove-it file backing README claims - -### CI - -- ci: redistribute concurrency-cancel guard to read-only check workflows (#32) -- ci: bump actions/upload-artifact SHA to current v4 (#22) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci: deploy dogfood-gate, fix hypatia-scan, add pre-commit hooks - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..f39d9ca --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,132 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +=== Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our +mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the +overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or +advances of any kind +* Trolling, insulting or derogatory comments, and personal or political +attacks +* Public or private harassment +* Publishing others’ private information, such as a physical or email +address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a +professional setting + +=== Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include using an +official e-mail address, posting via an official social media account, +or acting as an appointed representative at an online or offline event. + +=== Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement at . +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security +of the reporter of any incident. + +=== Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome in the community. + +*Consequence*: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. This includes avoiding interactions in community spaces as well as +external channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No +public or private interaction with the people involved, including +unsolicited interaction with those enforcing the Code of Conduct, is +allowed during this period. Violating these terms may lead to a +permanent ban. + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +=== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org[Contributor Covenant], version 2.0, +available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity[Mozilla’s code of conduct +enforcement ladder]. + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq. Translations are available +at https://www.contributor-covenant.org/translations. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 18c9147..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,128 +0,0 @@ -# Contributor Covenant Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, religion, or sexual identity -and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the - overall community - -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or - advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email - address, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official e-mail address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at -. -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series -of actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or -permanent ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within -the community. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. - -Community Impact Guidelines were inspired by [Mozilla's code of conduct -enforcement ladder](https://github.com/mozilla/diversity). - -[homepage]: https://www.contributor-covenant.org - -For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..e48f66c --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,111 @@ +== Clone the repository + +git clone +https://github.com/hyperpolymath/misinformation-defence-platform.git cd +misinformation-defence-platform + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create misinformation-defence-platform-dev toolbox enter +misinformation-defence-platform-dev # Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +misinformation-defence-platform/ ├── src/ # Source code (Perimeter 1-2) +├── lib/ # Library code (Perimeter 1-2) ├── extensions/ # Extensions +(Perimeter 2) ├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling +(Perimeter 2) ├── docs/ # Documentation (Perimeter 3) │ ├── +architecture/ # ADRs, specs (Perimeter 2) │ └── proposals/ # RFCs +(Perimeter 3) ├── examples/ # Examples (Perimeter 3) ├── spec/ # Spec +tests (Perimeter 3) ├── tests/ # Test suite (Perimeter 2-3) ├── +.well-known/ # Protocol files (Perimeter 1-3) ├── .github/ # GitHub +config (Perimeter 1) │ ├── ISSUE_TEMPLATE/ │ └── workflows/ ├── +CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md # This file ├── +GOVERNANCE.md ├── LICENSE ├── MAINTAINERS.md ├── README.adoc ├── +SECURITY.md ├── flake.nix # Nix flake (Perimeter 1) └── Justfile # Task +runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 7e4af22..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/misinformation-defence-platform.git -cd misinformation-defence-platform - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create misinformation-defence-platform-dev -toolbox enter misinformation-defence-platform-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -misinformation-defence-platform/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..7d5132f --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,12 @@ +== PROOF-NEEDS.md + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. + +When this project needs formal ABI verification, create domain-specific +Idris2 proofs following the pattern in repos like `+typed-wasm+`, +`+proven+`, `+echidna+`, or `+boj-server+`. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 8950320..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,10 +0,0 @@ -# PROOF-NEEDS.md - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. - -When this project needs formal ABI verification, create domain-specific Idris2 proofs -following the pattern in repos like `typed-wasm`, `proven`, `echidna`, or `boj-server`. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..6833c54 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,378 @@ +Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. Table of Contents + +.... +Reporting a Vulnerability +What to Include +Response Timeline +Disclosure Policy +Scope +Safe Harbour +Recognition +Security Updates +Security Best Practices +.... + +Reporting a Vulnerability Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +.... +Navigate to Report a Vulnerability +Click "Report a vulnerability" +Complete the form with as much detail as possible +Submit — we'll receive a private notification +.... + +This method ensures: + +.... +End-to-end encryption of your report +Private discussion space for collaboration +Coordinated disclosure tooling +Automatic credit when the advisory is published +.... + +Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +Email security@hyperpolymath.org PGP Key Download Public Key Fingerprint +See GPG key + +== Import our PGP key + +curl -sSL https://hyperpolymath.org/gpg/security.asc | gpg –import + +== Verify fingerprint + +gpg –fingerprint security@hyperpolymath.org + +== Encrypt your report + +gpg –armor –encrypt –recipient security@hyperpolymath.org report.txt + +.... +⚠️ Important: Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. +.... + +What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. Required Information + +.... +Description: Clear explanation of the vulnerability +Impact: What an attacker could achieve (confidentiality, integrity, availability) +Affected versions: Which versions/commits are affected +Reproduction steps: Detailed steps to reproduce the issue +.... + +Helpful Additional Information + +.... +Proof of concept: Code, scripts, or screenshots demonstrating the vulnerability +Attack scenario: Realistic attack scenario showing exploitability +CVSS score: Your assessment of severity (use CVSS 3.1 Calculator) +CWE ID: Common Weakness Enumeration identifier if known +Suggested fix: If you have ideas for remediation +References: Links to related vulnerabilities, research, or advisories +.... + +Example Report Structure + +=== Summary + +{empty}[One-sentence description of the vulnerability] + +=== Vulnerability Type + +{empty}[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +=== Affected Component + +{empty}[File path, function name, API endpoint, etc.] + +=== Affected Versions + +{empty}[Version range or specific commits] + +=== Severity Assessment + +* CVSS 3.1 Score: [X.X] +* CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +=== Description + +{empty}[Detailed technical description] + +=== Steps to Reproduce + +[arabic] +. [First step] +. [Second step] +. […] + +=== Proof of Concept + +{empty}[Code, curl commands, screenshots, etc.] + +=== Impact + +{empty}[What can an attacker achieve?] + +=== Suggested Remediation + +{empty}[Optional: your ideas for fixing] + +=== References + +{empty}[Links to related issues, CVEs, research] + +Response Timeline + +We commit to the following response times: Stage Timeframe Description +Initial Response 48 hours We acknowledge receipt and confirm we’re +investigating Triage 7 days We assess severity, confirm the +vulnerability, and estimate timeline Status Update Every 7 days Regular +updates on remediation progress Resolution 90 days Target for fix +development and release (complex issues may take longer) Disclosure 90 +days Public disclosure after fix is available (coordinated with you) + +.... +Note: These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. +.... + +Disclosure Policy + +We follow coordinated disclosure (also known as responsible disclosure): + +.... +You report the vulnerability privately +We acknowledge and begin investigation +We develop a fix and prepare a release +We coordinate disclosure timing with you +We publish security advisory and fix simultaneously +You may publish your research after disclosure +.... + +Our Commitments + +.... +We will not take legal action against researchers who follow this policy +We will work with you to understand and resolve the issue +We will credit you in the security advisory (unless you prefer anonymity) +We will notify you before public disclosure +We will publish advisories with sufficient detail for users to assess risk +.... + +Your Commitments + +.... +Report vulnerabilities promptly after discovery +Give us reasonable time to address the issue before disclosure +Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability +Do not degrade service availability (no DoS testing on production) +Do not share vulnerability details with others until coordinated disclosure +.... + +Disclosure Timeline + +Day 0 You report vulnerability Day 1-2 We acknowledge receipt Day 7 We +confirm vulnerability and share initial assessment Day 7-90 We develop +and test fix Day 90 Coordinated public disclosure (earlier if fix is +ready; later by mutual agreement) + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. Scope In Scope ✅ + +The following are within scope for security research: + +.... +This repository (hyperpolymath/terrapin-ssg) and all its code +Official releases and packages published from this repository +Documentation that could lead to security issues +Build and deployment configurations in this repository +Dependencies (report here, we'll coordinate with upstream) +.... + +Out of Scope ❌ + +The following are not in scope: + +.... +Third-party services we integrate with (report directly to them) +Social engineering attacks against maintainers +Physical security +Denial of service attacks against production infrastructure +Spam, phishing, or other non-technical attacks +Issues already reported or publicly known +Theoretical vulnerabilities without proof of concept +.... + +Qualifying Vulnerabilities + +We’re particularly interested in: + +.... +Remote code execution +SQL injection, command injection, code injection +Authentication/authorisation bypass +Cross-site scripting (XSS) and cross-site request forgery (CSRF) +Server-side request forgery (SSRF) +Path traversal / local file inclusion +Information disclosure (credentials, PII, secrets) +Cryptographic weaknesses +Deserialisation vulnerabilities +Memory safety issues (buffer overflows, use-after-free, etc.) +Supply chain vulnerabilities (dependency confusion, etc.) +Significant logic flaws +.... + +Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +.... +Missing security headers on non-sensitive pages +Clickjacking on pages without sensitive actions +Self-XSS (requires victim to paste code) +Missing rate limiting (unless it enables a specific attack) +Username/email enumeration (unless high-risk context) +Missing cookie flags on non-sensitive cookies +Software version disclosure +Verbose error messages (unless exposing secrets) +Best practice deviations without demonstrable impact +.... + +Safe Harbour + +We support security research conducted in good faith. Our Promise + +If you conduct security research in accordance with this policy: + +.... +✅ We will not initiate legal action against you +✅ We will not report your activity to law enforcement +✅ We will work with you in good faith to resolve issues +✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +✅ We waive any potential claim against you for circumvention of security controls +.... + +Good Faith Requirements + +To qualify for safe harbour, you must: + +.... +Comply with this security policy +Report vulnerabilities promptly +Avoid privacy violations (do not access others' data) +Avoid service degradation (no destructive testing) +Not exploit vulnerabilities beyond proof-of-concept +Not use vulnerabilities for profit (beyond bug bounties where offered) + +⚠️ Important: This safe harbour does not extend to third-party systems. Always check their policies before testing. +.... + +Recognition + +We believe in recognising security researchers who help us improve. Hall +of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +Security Acknowledgments (unless they prefer anonymity). + +Recognition includes: + +.... +Your name (or chosen alias) +Link to your website/profile (optional) +Brief description of the vulnerability class +Date of report +.... + +What We Offer + +.... +✅ Public credit in security advisories +✅ Acknowledgment in release notes +✅ Entry in our Hall of Fame +✅ Reference/recommendation letter upon request (for significant findings) +.... + +What We Don’t Currently Offer + +.... +❌ Monetary bug bounties +❌ Hardware or swag +❌ Paid security research contracts + +Note: We're a community project with limited resources. Your contributions help everyone who uses this software. +.... + +Security Updates Receiving Updates + +To stay informed about security updates: + +.... +Watch this repository: Click "Watch" → "Custom" → Select "Security alerts" +GitHub Security Advisories: Published at Security Advisories +Release notes: Security fixes noted in CHANGELOG +.... + +Update Policy Severity Response Critical/High Patch release as soon as +fix is ready Medium Included in next scheduled release (or earlier) Low +Included in next scheduled release Supported Versions Version Supported +Notes main branch ✅ Yes Latest development Latest release ✅ Yes +Current stable Previous minor release ✅ Yes Security fixes backported +Older versions ❌ No Please upgrade Security Best Practices + +When using terrapin-ssg, we recommend: General + +.... +Keep dependencies up to date +Use the latest stable release +Subscribe to security notifications +Review configuration against security documentation +Follow principle of least privilege +.... + +For Contributors + +.... +Never commit secrets, credentials, or API keys +Use signed commits (git config commit.gpgsign true) +Review dependencies before adding them +Run security linters locally before pushing +Report any concerns about existing code +.... + +Additional Resources + +.... +Our PGP Public Key +Security Advisories +Changelog +Contributing Guidelines +CVE Database +CVSS Calculator +.... + +Contact Purpose Contact Security issues Report via GitHub or +security@hyperpolymath.org General questions GitHub Discussions Other +enquiries See README for contact information Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +.... +Committed to this repository with a clear commit message +Noted in the changelog +Announced via GitHub Discussions (for major changes) +.... + +Thank you for helping keep terrapin-ssg and its users safe. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 5eb5e20..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,328 +0,0 @@ -Security Policy - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. -Table of Contents - - Reporting a Vulnerability - What to Include - Response Timeline - Disclosure Policy - Scope - Safe Harbour - Recognition - Security Updates - Security Best Practices - -Reporting a Vulnerability -Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - - Navigate to Report a Vulnerability - Click "Report a vulnerability" - Complete the form with as much detail as possible - Submit — we'll receive a private notification - -This method ensures: - - End-to-end encryption of your report - Private discussion space for collaboration - Coordinated disclosure tooling - Automatic credit when the advisory is published - -Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -Email security@hyperpolymath.org -PGP Key Download Public Key -Fingerprint See GPG key - -# Import our PGP key -curl -sSL https://hyperpolymath.org/gpg/security.asc | gpg --import - -# Verify fingerprint -gpg --fingerprint security@hyperpolymath.org - -# Encrypt your report -gpg --armor --encrypt --recipient security@hyperpolymath.org report.txt - - ⚠️ Important: Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - -What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. -Required Information - - Description: Clear explanation of the vulnerability - Impact: What an attacker could achieve (confidentiality, integrity, availability) - Affected versions: Which versions/commits are affected - Reproduction steps: Detailed steps to reproduce the issue - -Helpful Additional Information - - Proof of concept: Code, scripts, or screenshots demonstrating the vulnerability - Attack scenario: Realistic attack scenario showing exploitability - CVSS score: Your assessment of severity (use CVSS 3.1 Calculator) - CWE ID: Common Weakness Enumeration identifier if known - Suggested fix: If you have ideas for remediation - References: Links to related vulnerabilities, research, or advisories - -Example Report Structure - -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] - -Response Timeline - -We commit to the following response times: -Stage Timeframe Description -Initial Response 48 hours We acknowledge receipt and confirm we're investigating -Triage 7 days We assess severity, confirm the vulnerability, and estimate timeline -Status Update Every 7 days Regular updates on remediation progress -Resolution 90 days Target for fix development and release (complex issues may take longer) -Disclosure 90 days Public disclosure after fix is available (coordinated with you) - - Note: These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - -Disclosure Policy - -We follow coordinated disclosure (also known as responsible disclosure): - - You report the vulnerability privately - We acknowledge and begin investigation - We develop a fix and prepare a release - We coordinate disclosure timing with you - We publish security advisory and fix simultaneously - You may publish your research after disclosure - -Our Commitments - - We will not take legal action against researchers who follow this policy - We will work with you to understand and resolve the issue - We will credit you in the security advisory (unless you prefer anonymity) - We will notify you before public disclosure - We will publish advisories with sufficient detail for users to assess risk - -Your Commitments - - Report vulnerabilities promptly after discovery - Give us reasonable time to address the issue before disclosure - Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability - Do not degrade service availability (no DoS testing on production) - Do not share vulnerability details with others until coordinated disclosure - -Disclosure Timeline - -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. -Scope -In Scope ✅ - -The following are within scope for security research: - - This repository (hyperpolymath/terrapin-ssg) and all its code - Official releases and packages published from this repository - Documentation that could lead to security issues - Build and deployment configurations in this repository - Dependencies (report here, we'll coordinate with upstream) - -Out of Scope ❌ - -The following are not in scope: - - Third-party services we integrate with (report directly to them) - Social engineering attacks against maintainers - Physical security - Denial of service attacks against production infrastructure - Spam, phishing, or other non-technical attacks - Issues already reported or publicly known - Theoretical vulnerabilities without proof of concept - -Qualifying Vulnerabilities - -We're particularly interested in: - - Remote code execution - SQL injection, command injection, code injection - Authentication/authorisation bypass - Cross-site scripting (XSS) and cross-site request forgery (CSRF) - Server-side request forgery (SSRF) - Path traversal / local file inclusion - Information disclosure (credentials, PII, secrets) - Cryptographic weaknesses - Deserialisation vulnerabilities - Memory safety issues (buffer overflows, use-after-free, etc.) - Supply chain vulnerabilities (dependency confusion, etc.) - Significant logic flaws - -Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - - Missing security headers on non-sensitive pages - Clickjacking on pages without sensitive actions - Self-XSS (requires victim to paste code) - Missing rate limiting (unless it enables a specific attack) - Username/email enumeration (unless high-risk context) - Missing cookie flags on non-sensitive cookies - Software version disclosure - Verbose error messages (unless exposing secrets) - Best practice deviations without demonstrable impact - -Safe Harbour - -We support security research conducted in good faith. -Our Promise - -If you conduct security research in accordance with this policy: - - ✅ We will not initiate legal action against you - ✅ We will not report your activity to law enforcement - ✅ We will work with you in good faith to resolve issues - ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws - ✅ We waive any potential claim against you for circumvention of security controls - -Good Faith Requirements - -To qualify for safe harbour, you must: - - Comply with this security policy - Report vulnerabilities promptly - Avoid privacy violations (do not access others' data) - Avoid service degradation (no destructive testing) - Not exploit vulnerabilities beyond proof-of-concept - Not use vulnerabilities for profit (beyond bug bounties where offered) - - ⚠️ Important: This safe harbour does not extend to third-party systems. Always check their policies before testing. - -Recognition - -We believe in recognising security researchers who help us improve. -Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our Security Acknowledgments (unless they prefer anonymity). - -Recognition includes: - - Your name (or chosen alias) - Link to your website/profile (optional) - Brief description of the vulnerability class - Date of report - -What We Offer - - ✅ Public credit in security advisories - ✅ Acknowledgment in release notes - ✅ Entry in our Hall of Fame - ✅ Reference/recommendation letter upon request (for significant findings) - -What We Don't Currently Offer - - ❌ Monetary bug bounties - ❌ Hardware or swag - ❌ Paid security research contracts - - Note: We're a community project with limited resources. Your contributions help everyone who uses this software. - -Security Updates -Receiving Updates - -To stay informed about security updates: - - Watch this repository: Click "Watch" → "Custom" → Select "Security alerts" - GitHub Security Advisories: Published at Security Advisories - Release notes: Security fixes noted in CHANGELOG - -Update Policy -Severity Response -Critical/High Patch release as soon as fix is ready -Medium Included in next scheduled release (or earlier) -Low Included in next scheduled release -Supported Versions -Version Supported Notes -main branch ✅ Yes Latest development -Latest release ✅ Yes Current stable -Previous minor release ✅ Yes Security fixes backported -Older versions ❌ No Please upgrade -Security Best Practices - -When using terrapin-ssg, we recommend: -General - - Keep dependencies up to date - Use the latest stable release - Subscribe to security notifications - Review configuration against security documentation - Follow principle of least privilege - -For Contributors - - Never commit secrets, credentials, or API keys - Use signed commits (git config commit.gpgsign true) - Review dependencies before adding them - Run security linters locally before pushing - Report any concerns about existing code - -Additional Resources - - Our PGP Public Key - Security Advisories - Changelog - Contributing Guidelines - CVE Database - CVSS Calculator - -Contact -Purpose Contact -Security issues Report via GitHub or security@hyperpolymath.org -General questions GitHub Discussions -Other enquiries See README for contact information -Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - - Committed to this repository with a clear commit message - Noted in the changelog - Announced via GitHub Discussions (for major changes) - -Thank you for helping keep terrapin-ssg and its users safe. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..d58e6d2 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,113 @@ +== TEST-NEEDS.md — Test Coverage Status + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== CRG Grade: *C* (achieved 2026-04-04) + +==== Coverage Matrix + +[width="100%",cols="23%,64%,6%,7%",options="header",] +|=== +|Test Category |Location |Count |Status +|Unit tests (inline) |`+disinfo-nesy-detector/eval/src/baselines.rs+` |5 +|PASS + +|Unit tests (inline) |`+disinfo-nesy-detector/eval/src/datasets.rs+` |3 +|PASS + +|Unit tests (inline) +|`+disinfo-nesy-detector/eval/src/explainability.rs+` |4 |PASS + +|Unit tests (inline) |`+disinfo-nesy-detector/eval/src/metrics.rs+` |7 +|PASS + +|Unit tests (inline) |`+disinfo-nesy-detector/eval/src/pipeline.rs+` |3 +|PASS + +|Smoke / build |`+cargo build+` + `+cargo test+` (all crates) |— |PASS + +|P2P property tests +|`+disinfo-nesy-detector/eval/tests/property_tests.rs+` |11 |PASS + +|E2E tests |`+disinfo-nesy-detector/eval/tests/e2e_tests.rs+` |8 |PASS + +|Aspect tests |`+disinfo-nesy-detector/eval/tests/aspect_tests.rs+` |13 +|PASS + +|Benchmarks |`+disinfo-nesy-detector/eval/benches/detection_bench.rs+` +|12 |BASELINED +|=== + +*Total integration tests:* 57 (25 unit + 11 property + 8 E2E + 13 +aspect) + +==== Benchmark Baselines (2026-04-04, release profile) + +[cols=",",options="header",] +|=== +|Benchmark |Median time +|keyword/single_claim |~10.9 µs +|tfidf/single_claim |~69.6 µs +|tfidf/batch/10 |~1.26 ms +|tfidf/batch/100 |~6.1 ms +|tfidf/batch/1000 |~72 ms +|keyword/batch/1000 |~5.0 ms +|tfidf/train_1000_samples |~2.1 ms +|explain/keyword/disinfo |~23.4 µs +|explain/tfidf/disinfo |~64.3 µs +|explain/tfidf/authentic |~109.4 µs +|=== + +All single-claim detections are well within the 100 ms aspect test +limit. + +==== Property Invariants Verified + +* Confidence scores always in `+[0.0, 1.0]+` for all models and any text +input +* KeywordBaseline and MajorityBaseline are deterministic (same input → +same output) +* Majority class prediction is constant regardless of input +* Keyword explanation is non-empty for texts with matched keywords +* Label binary round-trip (Disinformation/Authentic) is stable +* `+predict_batch+` matches `+predict+` for all inputs (TF-IDF) +* Synthetic dataset split sizes always sum to total +* ExplanationBuilder preserves confidence exactly + +==== Aspect (Cross-Cutting) Coverage + +* Security: null bytes, oversized (100k chars), Unicode combining marks, +bidi overrides, non-ASCII symbols, repeated keywords — all handled +without panic +* Performance: single-claim detection verified < 100 ms for both models +* Error handling: empty string, whitespace-only, single char — all +handled +* Contract: label-probability consistency enforced for KeywordBaseline +* Robustness: mixed adversarial batch (8 edge-case variants) completes +cleanly + +==== What is Stubbed / Not Yet Implemented + +The following are not yet testable because the corresponding source is +not implemented (only the eval pipeline exists; the core +ONNX/neuro-symbolic detector is disabled pending model availability): + +* `+disinfo-nesy-detector/src/onnx_wrapper.rs+` — ONNX runtime is +commented out +* `+disinfo-nesy-detector/src/souffle_wrapper.rs+` — Soufflé Datalog +integration +* `+disinfo-nesy-detector/src/main.rs+` — NATS JetStream detector +service +* Contract tests against live NATS — require running NATS server +* Reflexive tests on model-card JSON schema — schema not yet published + +These should be added at CRG B when the core detector is implemented. + +==== Next Steps (CRG B) + +* [ ] Implement and test ONNX wrapper once model is available +* [ ] Contract tests against NATS JetStream API +* [ ] Reflexive tests: load saved eval results and re-verify metrics +* [ ] Mutation testing baseline +* [ ] CI integration: add `+cargo test && cargo bench --no-run+` to +quality.yml diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 7424502..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,84 +0,0 @@ -# TEST-NEEDS.md — Test Coverage Status - - - - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## CRG Grade: **C** (achieved 2026-04-04) - -### Coverage Matrix - -| Test Category | Location | Count | Status | -|----------------------|------------------------------------------------------------------|-------|--------| -| Unit tests (inline) | `disinfo-nesy-detector/eval/src/baselines.rs` | 5 | PASS | -| Unit tests (inline) | `disinfo-nesy-detector/eval/src/datasets.rs` | 3 | PASS | -| Unit tests (inline) | `disinfo-nesy-detector/eval/src/explainability.rs` | 4 | PASS | -| Unit tests (inline) | `disinfo-nesy-detector/eval/src/metrics.rs` | 7 | PASS | -| Unit tests (inline) | `disinfo-nesy-detector/eval/src/pipeline.rs` | 3 | PASS | -| Smoke / build | `cargo build` + `cargo test` (all crates) | — | PASS | -| P2P property tests | `disinfo-nesy-detector/eval/tests/property_tests.rs` | 11 | PASS | -| E2E tests | `disinfo-nesy-detector/eval/tests/e2e_tests.rs` | 8 | PASS | -| Aspect tests | `disinfo-nesy-detector/eval/tests/aspect_tests.rs` | 13 | PASS | -| Benchmarks | `disinfo-nesy-detector/eval/benches/detection_bench.rs` | 12 | BASELINED | - -**Total integration tests:** 57 (25 unit + 11 property + 8 E2E + 13 aspect) - -### Benchmark Baselines (2026-04-04, release profile) - -| Benchmark | Median time | -|----------------------------------|---------------| -| keyword/single_claim | ~10.9 µs | -| tfidf/single_claim | ~69.6 µs | -| tfidf/batch/10 | ~1.26 ms | -| tfidf/batch/100 | ~6.1 ms | -| tfidf/batch/1000 | ~72 ms | -| keyword/batch/1000 | ~5.0 ms | -| tfidf/train_1000_samples | ~2.1 ms | -| explain/keyword/disinfo | ~23.4 µs | -| explain/tfidf/disinfo | ~64.3 µs | -| explain/tfidf/authentic | ~109.4 µs | - -All single-claim detections are well within the 100 ms aspect test limit. - -### Property Invariants Verified - -- Confidence scores always in `[0.0, 1.0]` for all models and any text input -- KeywordBaseline and MajorityBaseline are deterministic (same input → same output) -- Majority class prediction is constant regardless of input -- Keyword explanation is non-empty for texts with matched keywords -- Label binary round-trip (Disinformation/Authentic) is stable -- `predict_batch` matches `predict` for all inputs (TF-IDF) -- Synthetic dataset split sizes always sum to total -- ExplanationBuilder preserves confidence exactly - -### Aspect (Cross-Cutting) Coverage - -- Security: null bytes, oversized (100k chars), Unicode combining marks, - bidi overrides, non-ASCII symbols, repeated keywords — all handled without panic -- Performance: single-claim detection verified < 100 ms for both models -- Error handling: empty string, whitespace-only, single char — all handled -- Contract: label-probability consistency enforced for KeywordBaseline -- Robustness: mixed adversarial batch (8 edge-case variants) completes cleanly - -### What is Stubbed / Not Yet Implemented - -The following are not yet testable because the corresponding source is not -implemented (only the eval pipeline exists; the core ONNX/neuro-symbolic -detector is disabled pending model availability): - -- `disinfo-nesy-detector/src/onnx_wrapper.rs` — ONNX runtime is commented out -- `disinfo-nesy-detector/src/souffle_wrapper.rs` — Soufflé Datalog integration -- `disinfo-nesy-detector/src/main.rs` — NATS JetStream detector service -- Contract tests against live NATS — require running NATS server -- Reflexive tests on model-card JSON schema — schema not yet published - -These should be added at CRG B when the core detector is implemented. - -### Next Steps (CRG B) - -- [ ] Implement and test ONNX wrapper once model is available -- [ ] Contract tests against NATS JetStream API -- [ ] Reflexive tests: load saved eval results and re-verify metrics -- [ ] Mutation testing baseline -- [ ] CI integration: add `cargo test && cargo bench --no-run` to quality.yml diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 87% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 983ef99..4966b11 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Misinformation Defence Platform — Project Topology -# Misinformation Defence Platform — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ DEFENCE ANALYST │ │ (Detection HUD / API Client) │ @@ -40,11 +36,11 @@ │ Justfile Automation .machine_readable/ │ │ Mustfile / Deno 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── PLATFORM CORE @@ -64,25 +60,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██░░░░░░░░ ~20% Specification Phase -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Platform Spec ───► Infrastructure ───► Detector Logic ───► Channel Audit │ │ │ │ ▼ ▼ ▼ ▼ CCCP Policy ───► CI Workflows ─────► Algorithm Shield ──► Response -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/defensive-multiplicity/ABI-FFI-README.md b/algorithm-shield/ABI-FFI-README.adoc similarity index 74% rename from defensive-multiplicity/ABI-FFI-README.md rename to algorithm-shield/ABI-FFI-README.adoc index f06f72c..f1163e3 100644 --- a/defensive-multiplicity/ABI-FFI-README.md +++ b/algorithm-shield/ABI-FFI-README.adoc @@ -1,19 +1,22 @@ -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -45,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -77,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -97,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -111,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -125,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -140,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -215,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -237,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -259,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -282,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -312,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -342,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/algorithm-shield/ARCHITECTURE.adoc b/algorithm-shield/ARCHITECTURE.adoc new file mode 100644 index 0000000..2c77c69 --- /dev/null +++ b/algorithm-shield/ARCHITECTURE.adoc @@ -0,0 +1,484 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) 2026 +hyperpolymath // Part of Algorithm Shield - +https://github.com/hyperpolymath/algorithm-shield + +== Algorithm Shield - Architecture Overview + +*Quick Reference*: Key architectural decisions and technology stack + +''''' + +=== Strategic Direction (User-Approved ✅) + +*Hybrid Architecture*: ReScript + Rust + Ephapax (incremental adoption) + +*Not a complete rewrite* - Profile-guided optimization of hot paths only + +*Integration*: Svalinn/Vörðr/Cerro Torre verified container stack +(v2.0+) + +''''' + +=== Version Roadmap + +==== v1.0 (Jun 2026) - Pure Rust MVP ✅ + +*Goal*: Ship production-ready browser extension + +*Tech Stack*: - ReScript: UI, state management, browser API bindings - +Rust/WASM: Rule engine (180KB, 5ms/rule) - Deno: Build tooling + +*Focus*: Prove core concept, collect performance metrics + +''''' + +==== v2.0 (Dec 2026) - Hybrid + Containerization + +*Goal*: Performance optimization + enterprise features + +*Tech Stack*: - ReScript: UI (no change) - Rust: FFI, serialization, I/O +(80% of codebase) - *Ephapax*: Hot paths only - condition evaluation, +action generation (20% of codebase) - *Cerro Torre*: Package WASM as +.ctp bundles (cryptographic provenance) - *Svalinn* (Enterprise): Edge +gateway for policy enforcement, OAuth2/SSO - *Vörðr* (v5.0+): Container +runtime for formal verification + +*Performance Targets*: - 1.8× faster rule evaluation (Ephapax regions) - +140KB WASM (down from 180KB) - 64MB memory per container (down from +256MB) + +*Formal Verification Stack*: + +.... +Layer 4: SPARK (Cerro Torre) - Cryptographic operations proven +Layer 3: Coq (Ephapax) - Memory safety proven (no use-after-free, no leaks) +Layer 2: Idris2 (Ephapax) - Linear types enforce affine constraints +Layer 1: Idris2 (Vörðr) - Container state transitions proven +.... + +*Deliverables*: 1. Profile production metrics (3 months) 2. Identify top +3 bottlenecks 3. Rewrite only hot paths in Ephapax (2 months) 4. Package +with Cerro Torre (.ctp bundles) 5. Optional Svalinn gateway for +enterprise + +''''' + +==== v5.0 (Jun 2027) - Full Containerization + +*Goal*: Production deployment in Vörðr containers + +*New Features*: - Vörðr container runtime (Elixir/Rust/Idris2/SPARK) - +Bennett-reversible operations (rollback bad rules) - BEAM fault +tolerance (auto-restart crashed containers) - Parallel rule evaluation +(10-12× speedup for 500+ rules) - Federated bubble map (crowdsourced +topology) + +*Decision Point (Dec 2026)*: - If hybrid approach meets needs → stay +hybrid - If users complain about speed → expand Ephapax usage - If +enterprise demands formal verification → increase Coq coverage + +''''' + +=== Technology Stack + +[width="100%",cols="26%,42%,32%",options="header",] +|=== +|Layer |Technology |Purpose +|*UI* |ReScript |Popup, control panel, state management + +|*Accessibility* |ARIA + Semantic HTML |WCAG 2.3 AAA compliance, screen +reader support + +|*Security* |Validation + Sanitization |XSS prevention, input +validation, CSP enforcement + +|*Browser APIs* |ReScript bindings |chrome.storage, chrome.tabs, +chrome.runtime + +|*Glue Layer* |Rust |JSON serialization, FFI coordination, storage + +|*Hot Paths* |Ephapax (v2.0+) |Condition evaluation, action generation + +|*Cold Paths* |Rust |Everything else (I/O, FFI, serialization) + +|*Build* |Deno |Build scripts, bundling (no Node/npm/bun per RSR) + +|*Packaging* |Cerro Torre (v2.0+) |.ctp bundles with provenance + +|*Gateway* |Svalinn (v2.0+ Enterprise) |Policy enforcement, OAuth2/SSO + +|*Runtime* |Vörðr (v5.0+) |Formal verification, reversibility +|=== + +''''' + +=== Component Distribution (v2.0 Target) + +.... +┌────────────────────────────────────────────────────────────┐ +│ Algorithm Shield (Hybrid) │ +├────────────────────────────────────────────────────────────┤ +│ │ +│ ReScript (UI & Orchestration) ~40KB │ +│ ├─ Popup UI │ +│ ├─ State management │ +│ └─ Browser API bindings │ +│ │ +│ Rust WASM (Glue Layer) ~60KB │ +│ ├─ JSON serialization (serde) │ +│ ├─ FFI coordination (wasm-bindgen) │ +│ ├─ Storage integration │ +│ └─ Non-critical rule processing │ +│ │ +│ Ephapax WASM (Performance-Critical Core) ~80KB │ +│ ├─ Condition evaluation (tight loops) ✅ │ +│ ├─ Action generation (region-based) ✅ │ +│ ├─ Pattern matching (miniKaren unification) ✅ │ +│ └─ Coq-proven correctness 📊 │ +│ │ +│ Total WASM: ~140KB │ +│ (down from 180KB pure Rust) │ +└────────────────────────────────────────────────────────────┘ +.... + +''''' + +=== Performance Comparison + +[cols=",,,",options="header",] +|=== +|Metric |v1.0 (Rust) |v2.0 (Hybrid) |v5.0+ (Vörðr) +|Single rule eval |5ms |3ms (1.67×) |3ms +|100 rules batch |500ms |300ms (1.67×) |45ms (11×) +|WASM size |180KB |140KB (-22%) |120KB (-33%) +|Memory/container |256MB |64MB (-75%) |64MB +|Formal verification |None |Coq (hot paths) |SPARK+Coq+Idris2 +|=== + +''''' + +=== Formal Guarantees (v2.0+) + +==== Coq-Proven (Ephapax Core) + +From `+ephapax/formal/*.v+`: + +[arabic] +. *Type Soundness*: Well-typed programs don’t crash (Progress + +Preservation theorems) +. *No Use-After-Free*: Linear values cannot be accessed after +consumption +. *No Memory Leaks*: All linear values must be consumed exactly once +. *Region Safety*: Region deallocation cannot create dangling pointers + +==== SPARK-Proven (Cerro Torre Packaging) + +From `+cerro-torre/src/core/*.adb+`: + +[arabic] +. *Cryptographic Correctness*: SHA-256, Ed25519 signatures (FIPS 180-4, +RFC 8032) +. *No Integer Overflow*: All arithmetic proven safe +. *No Buffer Overruns*: Array accesses proven in-bounds + +==== Idris2-Proven (Vörðr Runtime, v5.0+) + +[arabic] +. *State Transition Correctness*: Container lifecycle proven valid +. *Reversibility*: All operations can be undone (Bennett’s theorem) + +''''' + +=== Key Architectural Decisions (ADRs) + +See `+META.scm+` for full ADRs. Summary: + +* *ADR-001*: ReScript for application logic (type safety, RSR +compliance) +* *ADR-002*: Rust/WASM for rule engine (performance, WASM target) +* *ADR-003*: Manifest v3 (future-proof, official requirement) +* *ADR-004*: Deno for build tooling (RSR compliance, no Node/npm) +* *ADR-007*: ✅ *Hybrid Ephapax/Rust* (incremental, profile-guided, not +complete rewrite) +* *ADR-008*: ✅ *Integration with Svalinn/Vörðr/Cerro Torre* (formal +verification stack) +* *ADR-009*: ✅ *Profile-guided optimization* (data-driven, 80/20 rule) + +''''' + +=== Migration Strategy + +==== Phase 1: Production Metrics (v1.0 - Jun 2026) + +Ship pure Rust, instrument for metrics: - Rule evaluation timing - +Memory usage - WASM size - User-reported performance issues + +Collect 3+ months of data. + +''''' + +==== Phase 2: Hot Path Identification (v2.0 - Sep 2026) + +Profile production data, identify bottlenecks: - Top 3 slowest +operations - Memory allocation hot spots - CPU-intensive loops + +Expected hot paths: 1. Condition evaluation (tight loops, heavy +allocation) 2. Action generation (many small objects) 3. Pattern +matching (recursive algorithms) + +''''' + +==== Phase 3: Incremental Rewrite (v2.0 - Oct-Nov 2026) + +Rewrite ONLY proven bottlenecks in Ephapax: - Month 1: Condition +evaluator (Ephapax) - Month 2: Action generator (Ephapax) - Benchmark: +Must show ≥30% improvement + +Keep everything else in Rust. + +''''' + +==== Phase 4: Containerization (v2.0 - Dec 2026) + +Package with verified container stack: - Cerro Torre: .ctp bundles with +provenance - Svalinn (optional): Enterprise policy gateway - Deploy +hybrid WASM (140KB) + +''''' + +==== Phase 5: Full Verification (v5.0 - Jun 2027) + +If justified by metrics: - Vörðr container runtime - Parallel rule +evaluation - Complete formal verification chain + +''''' + +=== Development Workflow + +[source,bash] +---- +# 1. Develop ReScript UI +cd src/rescript +npx rescript build + +# 2. Develop Rust glue layer +cd src/rust +cargo build --release --target wasm32-wasi + +# 3. Develop Ephapax hot paths (v2.0+) +cd src/ephapax +ephapax-cli compile-affine rule_engine.eph -o rule_engine.wasm + +# 4. Bundle all WASM +cd ../.. +deno run build.ts + +# 5. Package with Cerro Torre (v2.0+) +ct pack dist/algorithm_shield_engine.wasm \ + -o algorithm-shield.ctp \ + --sign-with keyring.asc + +# 6. Test in browser +# Load dist/ as unpacked extension in chrome://extensions +---- + +''''' + +=== Integration Points + +==== ReScript ↔ Rust + +[source,rescript] +---- +// ReScript side +@module("../wasm/algorithm_shield_engine.js") +external evaluateRule: (string, string) => promise = "evaluate_rule" + +let result = await evaluateRule(ruleJson, contextJson) +---- + +[source,rust] +---- +// Rust side +#[wasm_bindgen] +pub fn evaluate_rule(rule_json: &str, context_json: &str) -> String { + // Deserialize, call Ephapax hot path, serialize result +} +---- + +''''' + +==== Rust ↔ Ephapax (v2.0+) + +[source,rust] +---- +// Rust wrapper +extern "C" { + fn ephapax_evaluate_conditions( + conditions: *const Condition, + len: usize, + context: *const Context + ) -> *const Action; +} + +pub fn evaluate_rule(rule: &Rule, context: &Context) -> Vec { + unsafe { + let actions_ptr = ephapax_evaluate_conditions( + rule.conditions.as_ptr(), + rule.conditions.len(), + context as *const Context + ); + ptr_to_vec(actions_ptr) + } +} +---- + +[source,ephapax] +---- +-- Ephapax hot path +extern "C" fn ephapax_evaluate_conditions(...) -> *const Action { + region r { + let! result = evaluate@r(conditions, context) in + to_raw_ptr(result) + } + -- Region exits: O(1) cleanup +} +---- + +''''' + +=== Security Boundaries + +.... +┌────────────────────────────────────────────────────┐ +│ Browser Sandbox (built-in) │ +│ ┌──────────────────────────────────────────────┐ │ +│ │ Extension Process (Manifest v3) │ │ +│ │ ┌────────────────────────────────────────┐ │ │ +│ │ │ Security Layer (v0.1.1+) │ │ │ +│ │ │ - Input validation (type/range/enum) │ │ │ +│ │ │ - XSS prevention (sanitize) │ │ │ +│ │ │ - Message validation (whitelist) │ │ │ +│ │ │ - Strict CSP enforcement │ │ │ +│ │ │ ┌──────────────────────────────────┐ │ │ │ +│ │ │ │ WASM Sandbox (compile-time) │ │ │ │ +│ │ │ │ ┌────────────────────────────┐ │ │ │ │ +│ │ │ │ │ Svalinn Container (v2.0+) │ │ │ │ │ +│ │ │ │ │ ┌────────────────────────┐ │ │ │ │ │ +│ │ │ │ │ │ Vörðr Container (v5.0+)│ │ │ │ │ │ +│ │ │ │ │ │ - Idris2 proven │ │ │ │ │ │ +│ │ │ │ │ │ - BEAM fault tolerance │ │ │ │ │ │ +│ │ │ │ │ │ - eBPF monitoring │ │ │ │ │ │ +│ │ │ │ │ └────────────────────────┘ │ │ │ │ │ +│ │ │ │ └────────────────────────────┘ │ │ │ │ +│ │ │ └──────────────────────────────────┘ │ │ │ +│ │ └────────────────────────────────────────┘ │ │ +│ └──────────────────────────────────────────────┘ │ +└────────────────────────────────────────────────────┘ +.... + +*Defense in Depth*: 6 layers of isolation (v0.1.1+) - *Layer 1*: Browser +sandbox (built-in) - *Layer 2*: Extension process (Manifest v3 service +worker) - *Layer 3*: Security layer (input validation, XSS prevention) ← +NEW v0.1.1 - *Layer 4*: WASM sandbox (compile-time memory safety) - +*Layer 5*: Svalinn container (v2.0+, optional) - *Layer 6*: Vörðr +container (v5.0+, full formal verification) + +''''' + +=== Documentation + +* `+README.adoc+` - Project overview +* `+docs/SEAM-ANALYSIS.adoc+` - Integration point analysis +* `+docs/ROADMAP.adoc+` - Version evolution plan +* `+docs/SECURITY-ACCESSIBILITY-CHECKLIST.adoc+` - WCAG 2.3 AAA & +security compliance ← NEW v0.1.1 +* `+docs/SESSION-SUMMARY-20260124-SECURITY-ACCESSIBILITY.md+` - +Implementation details ← NEW v0.1.1 +* `+docs/DEFENSE-LAYERS.adoc+` - OSI layer security analysis +* `+docs/COMPETITIVE-LANDSCAPE.adoc+` - Comparison with existing tools +* `+docs/NETWORK-PROTOCOLS.adoc+` - IPv6, QUIC, HTTP/3, SPARK +integration +* `+docs/CONTAINERIZATION-ANALYSIS.adoc+` - Svalinn/Vörðr/Cerro Torre +integration +* `+docs/EPHAPAX-PERFORMANCE.adoc+` - Performance benchmarks, Coq proofs +* `+docs/EPHAPAX-MIGRATION-STRATEGY.adoc+` - Incremental adoption plan +* `+STATE.scm+` - Current project state +* `+META.scm+` - Architecture decision records (ADRs) +* `+ECOSYSTEM.scm+` - Position in hyperpolymath ecosystem + +''''' + +=== Repository + +*GitHub*: https://github.com/hyperpolymath/algorithm-shield + +*Status*: Early development (v0.1.1), 75% complete - ✅ Phase 1 +(Security & Accessibility) COMPLETE - 🟡 Phase 2 (Live Testing) In +Progress - 🔜 Phase 3 (v0.5 MVP) Planned + +*License*: MPL-2.0 (Palimpsest-MPL) + +''''' + +=== Key Insight + +*The membrane operates at every layer - but not every layer needs +Ephapax.* + +Use the right tool for each job: - *ReScript*: User interface +(type-safe, functional, React-like) - *Rust*: FFI, I/O, serialization +(mature ecosystem, excellent tooling) - *Ephapax*: Performance-critical +cores (linear types, regions, Coq proofs) + +*80/20 rule*: 20% of code (hot paths) accounts for 80% of runtime. + +Optimize the 20% that matters, keep the 80% simple. + +''''' + +=== Recent Changes (v0.1.1 - 2026-01-24) + +==== Security Hardening ✅ + +*New Security Module* (`+dist/popup.js+`): - `+Security.sanitizeText()+` +- Prevents XSS via text injection - `+Security.validateState()+` - +Type/range/enum validation - `+Security.validateMessage()+` - +Whitelist-based message filtering - `+Security.sanitizeHTML()+` - +Removes scripts and event handlers + +*Strengthened CSP*: + +.... +default-src 'self'; +script-src 'self' 'wasm-unsafe-eval'; +object-src 'none'; ← Blocks plugins +frame-ancestors 'none'; ← Prevents clickjacking +upgrade-insecure-requests; ← Forces HTTPS +.... + +==== Accessibility (WCAG 2.3 AAA) ✅ + +*New Accessibility Module* (`+dist/popup.js+`): - Full keyboard +navigation (Tab, Arrow keys, Escape) - Screen reader support (ARIA +labels, live regions, semantic HTML) - Context-sensitive help (tooltips +on all controls) - AAA color contrast (14.6:1 ratio achieved) - Reduced +motion support (`+prefers-reduced-motion+`) - High contrast mode +(`+prefers-contrast: high+`) + +*18/18 WCAG 2.3 AAA criteria met.* + +==== Seams Progress ✅ + +[cols=",,,",options="header",] +|=== +|Seam |Before |After |Status +|Seam 2 (ReScript ↔ WASM) |80% |100% |✅ *CLOSED* +|Seam 4 (Popup ↔ State) |80% |95% |✅ *SEALED* +|Seam 1 (ReScript ↔ Browser) |60% |75% |✅ *SMOOTHED* +|Seam 3 (Content ↔ DOM) |30% |75% |🟡 Improved +|=== + +''''' + +_Last updated: 2026-01-24 (v0.1.1)_ diff --git a/algorithm-shield/ARCHITECTURE.md b/algorithm-shield/ARCHITECTURE.md deleted file mode 100644 index c2a4ad5..0000000 --- a/algorithm-shield/ARCHITECTURE.md +++ /dev/null @@ -1,464 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) 2026 hyperpolymath -// Part of Algorithm Shield - https://github.com/hyperpolymath/algorithm-shield - -# Algorithm Shield - Architecture Overview - -**Quick Reference**: Key architectural decisions and technology stack - ---- - -## Strategic Direction (User-Approved ✅) - -**Hybrid Architecture**: ReScript + Rust + Ephapax (incremental adoption) - -**Not a complete rewrite** - Profile-guided optimization of hot paths only - -**Integration**: Svalinn/Vörðr/Cerro Torre verified container stack (v2.0+) - ---- - -## Version Roadmap - -### v1.0 (Jun 2026) - Pure Rust MVP ✅ - -**Goal**: Ship production-ready browser extension - -**Tech Stack**: -- ReScript: UI, state management, browser API bindings -- Rust/WASM: Rule engine (180KB, 5ms/rule) -- Deno: Build tooling - -**Focus**: Prove core concept, collect performance metrics - ---- - -### v2.0 (Dec 2026) - Hybrid + Containerization - -**Goal**: Performance optimization + enterprise features - -**Tech Stack**: -- ReScript: UI (no change) -- Rust: FFI, serialization, I/O (80% of codebase) -- **Ephapax**: Hot paths only - condition evaluation, action generation (20% of codebase) -- **Cerro Torre**: Package WASM as .ctp bundles (cryptographic provenance) -- **Svalinn** (Enterprise): Edge gateway for policy enforcement, OAuth2/SSO -- **Vörðr** (v5.0+): Container runtime for formal verification - -**Performance Targets**: -- 1.8× faster rule evaluation (Ephapax regions) -- 140KB WASM (down from 180KB) -- 64MB memory per container (down from 256MB) - -**Formal Verification Stack**: -``` -Layer 4: SPARK (Cerro Torre) - Cryptographic operations proven -Layer 3: Coq (Ephapax) - Memory safety proven (no use-after-free, no leaks) -Layer 2: Idris2 (Ephapax) - Linear types enforce affine constraints -Layer 1: Idris2 (Vörðr) - Container state transitions proven -``` - -**Deliverables**: -1. Profile production metrics (3 months) -2. Identify top 3 bottlenecks -3. Rewrite only hot paths in Ephapax (2 months) -4. Package with Cerro Torre (.ctp bundles) -5. Optional Svalinn gateway for enterprise - ---- - -### v5.0 (Jun 2027) - Full Containerization - -**Goal**: Production deployment in Vörðr containers - -**New Features**: -- Vörðr container runtime (Elixir/Rust/Idris2/SPARK) -- Bennett-reversible operations (rollback bad rules) -- BEAM fault tolerance (auto-restart crashed containers) -- Parallel rule evaluation (10-12× speedup for 500+ rules) -- Federated bubble map (crowdsourced topology) - -**Decision Point (Dec 2026)**: -- If hybrid approach meets needs → stay hybrid -- If users complain about speed → expand Ephapax usage -- If enterprise demands formal verification → increase Coq coverage - ---- - -## Technology Stack - -| Layer | Technology | Purpose | -|-------|------------|---------| -| **UI** | ReScript | Popup, control panel, state management | -| **Accessibility** | ARIA + Semantic HTML | WCAG 2.3 AAA compliance, screen reader support | -| **Security** | Validation + Sanitization | XSS prevention, input validation, CSP enforcement | -| **Browser APIs** | ReScript bindings | chrome.storage, chrome.tabs, chrome.runtime | -| **Glue Layer** | Rust | JSON serialization, FFI coordination, storage | -| **Hot Paths** | Ephapax (v2.0+) | Condition evaluation, action generation | -| **Cold Paths** | Rust | Everything else (I/O, FFI, serialization) | -| **Build** | Deno | Build scripts, bundling (no Node/npm/bun per RSR) | -| **Packaging** | Cerro Torre (v2.0+) | .ctp bundles with provenance | -| **Gateway** | Svalinn (v2.0+ Enterprise) | Policy enforcement, OAuth2/SSO | -| **Runtime** | Vörðr (v5.0+) | Formal verification, reversibility | - ---- - -## Component Distribution (v2.0 Target) - -``` -┌────────────────────────────────────────────────────────────┐ -│ Algorithm Shield (Hybrid) │ -├────────────────────────────────────────────────────────────┤ -│ │ -│ ReScript (UI & Orchestration) ~40KB │ -│ ├─ Popup UI │ -│ ├─ State management │ -│ └─ Browser API bindings │ -│ │ -│ Rust WASM (Glue Layer) ~60KB │ -│ ├─ JSON serialization (serde) │ -│ ├─ FFI coordination (wasm-bindgen) │ -│ ├─ Storage integration │ -│ └─ Non-critical rule processing │ -│ │ -│ Ephapax WASM (Performance-Critical Core) ~80KB │ -│ ├─ Condition evaluation (tight loops) ✅ │ -│ ├─ Action generation (region-based) ✅ │ -│ ├─ Pattern matching (miniKaren unification) ✅ │ -│ └─ Coq-proven correctness 📊 │ -│ │ -│ Total WASM: ~140KB │ -│ (down from 180KB pure Rust) │ -└────────────────────────────────────────────────────────────┘ -``` - ---- - -## Performance Comparison - -| Metric | v1.0 (Rust) | v2.0 (Hybrid) | v5.0+ (Vörðr) | -|--------|-------------|---------------|---------------| -| Single rule eval | 5ms | 3ms (1.67×) | 3ms | -| 100 rules batch | 500ms | 300ms (1.67×) | 45ms (11×) | -| WASM size | 180KB | 140KB (-22%) | 120KB (-33%) | -| Memory/container | 256MB | 64MB (-75%) | 64MB | -| Formal verification | None | Coq (hot paths) | SPARK+Coq+Idris2 | - ---- - -## Formal Guarantees (v2.0+) - -### Coq-Proven (Ephapax Core) - -From `ephapax/formal/*.v`: - -1. **Type Soundness**: Well-typed programs don't crash (Progress + Preservation theorems) -2. **No Use-After-Free**: Linear values cannot be accessed after consumption -3. **No Memory Leaks**: All linear values must be consumed exactly once -4. **Region Safety**: Region deallocation cannot create dangling pointers - -### SPARK-Proven (Cerro Torre Packaging) - -From `cerro-torre/src/core/*.adb`: - -1. **Cryptographic Correctness**: SHA-256, Ed25519 signatures (FIPS 180-4, RFC 8032) -2. **No Integer Overflow**: All arithmetic proven safe -3. **No Buffer Overruns**: Array accesses proven in-bounds - -### Idris2-Proven (Vörðr Runtime, v5.0+) - -1. **State Transition Correctness**: Container lifecycle proven valid -2. **Reversibility**: All operations can be undone (Bennett's theorem) - ---- - -## Key Architectural Decisions (ADRs) - -See `META.scm` for full ADRs. Summary: - -- **ADR-001**: ReScript for application logic (type safety, RSR compliance) -- **ADR-002**: Rust/WASM for rule engine (performance, WASM target) -- **ADR-003**: Manifest v3 (future-proof, official requirement) -- **ADR-004**: Deno for build tooling (RSR compliance, no Node/npm) -- **ADR-007**: ✅ **Hybrid Ephapax/Rust** (incremental, profile-guided, not complete rewrite) -- **ADR-008**: ✅ **Integration with Svalinn/Vörðr/Cerro Torre** (formal verification stack) -- **ADR-009**: ✅ **Profile-guided optimization** (data-driven, 80/20 rule) - ---- - -## Migration Strategy - -### Phase 1: Production Metrics (v1.0 - Jun 2026) - -Ship pure Rust, instrument for metrics: -- Rule evaluation timing -- Memory usage -- WASM size -- User-reported performance issues - -Collect 3+ months of data. - ---- - -### Phase 2: Hot Path Identification (v2.0 - Sep 2026) - -Profile production data, identify bottlenecks: -- Top 3 slowest operations -- Memory allocation hot spots -- CPU-intensive loops - -Expected hot paths: -1. Condition evaluation (tight loops, heavy allocation) -2. Action generation (many small objects) -3. Pattern matching (recursive algorithms) - ---- - -### Phase 3: Incremental Rewrite (v2.0 - Oct-Nov 2026) - -Rewrite ONLY proven bottlenecks in Ephapax: -- Month 1: Condition evaluator (Ephapax) -- Month 2: Action generator (Ephapax) -- Benchmark: Must show ≥30% improvement - -Keep everything else in Rust. - ---- - -### Phase 4: Containerization (v2.0 - Dec 2026) - -Package with verified container stack: -- Cerro Torre: .ctp bundles with provenance -- Svalinn (optional): Enterprise policy gateway -- Deploy hybrid WASM (140KB) - ---- - -### Phase 5: Full Verification (v5.0 - Jun 2027) - -If justified by metrics: -- Vörðr container runtime -- Parallel rule evaluation -- Complete formal verification chain - ---- - -## Development Workflow - -```bash -# 1. Develop ReScript UI -cd src/rescript -npx rescript build - -# 2. Develop Rust glue layer -cd src/rust -cargo build --release --target wasm32-wasi - -# 3. Develop Ephapax hot paths (v2.0+) -cd src/ephapax -ephapax-cli compile-affine rule_engine.eph -o rule_engine.wasm - -# 4. Bundle all WASM -cd ../.. -deno run build.ts - -# 5. Package with Cerro Torre (v2.0+) -ct pack dist/algorithm_shield_engine.wasm \ - -o algorithm-shield.ctp \ - --sign-with keyring.asc - -# 6. Test in browser -# Load dist/ as unpacked extension in chrome://extensions -``` - ---- - -## Integration Points - -### ReScript ↔ Rust - -```rescript -// ReScript side -@module("../wasm/algorithm_shield_engine.js") -external evaluateRule: (string, string) => promise = "evaluate_rule" - -let result = await evaluateRule(ruleJson, contextJson) -``` - -```rust -// Rust side -#[wasm_bindgen] -pub fn evaluate_rule(rule_json: &str, context_json: &str) -> String { - // Deserialize, call Ephapax hot path, serialize result -} -``` - ---- - -### Rust ↔ Ephapax (v2.0+) - -```rust -// Rust wrapper -extern "C" { - fn ephapax_evaluate_conditions( - conditions: *const Condition, - len: usize, - context: *const Context - ) -> *const Action; -} - -pub fn evaluate_rule(rule: &Rule, context: &Context) -> Vec { - unsafe { - let actions_ptr = ephapax_evaluate_conditions( - rule.conditions.as_ptr(), - rule.conditions.len(), - context as *const Context - ); - ptr_to_vec(actions_ptr) - } -} -``` - -```ephapax --- Ephapax hot path -extern "C" fn ephapax_evaluate_conditions(...) -> *const Action { - region r { - let! result = evaluate@r(conditions, context) in - to_raw_ptr(result) - } - -- Region exits: O(1) cleanup -} -``` - ---- - -## Security Boundaries - -``` -┌────────────────────────────────────────────────────┐ -│ Browser Sandbox (built-in) │ -│ ┌──────────────────────────────────────────────┐ │ -│ │ Extension Process (Manifest v3) │ │ -│ │ ┌────────────────────────────────────────┐ │ │ -│ │ │ Security Layer (v0.1.1+) │ │ │ -│ │ │ - Input validation (type/range/enum) │ │ │ -│ │ │ - XSS prevention (sanitize) │ │ │ -│ │ │ - Message validation (whitelist) │ │ │ -│ │ │ - Strict CSP enforcement │ │ │ -│ │ │ ┌──────────────────────────────────┐ │ │ │ -│ │ │ │ WASM Sandbox (compile-time) │ │ │ │ -│ │ │ │ ┌────────────────────────────┐ │ │ │ │ -│ │ │ │ │ Svalinn Container (v2.0+) │ │ │ │ │ -│ │ │ │ │ ┌────────────────────────┐ │ │ │ │ │ -│ │ │ │ │ │ Vörðr Container (v5.0+)│ │ │ │ │ │ -│ │ │ │ │ │ - Idris2 proven │ │ │ │ │ │ -│ │ │ │ │ │ - BEAM fault tolerance │ │ │ │ │ │ -│ │ │ │ │ │ - eBPF monitoring │ │ │ │ │ │ -│ │ │ │ │ └────────────────────────┘ │ │ │ │ │ -│ │ │ │ └────────────────────────────┘ │ │ │ │ -│ │ │ └──────────────────────────────────┘ │ │ │ -│ │ └────────────────────────────────────────┘ │ │ -│ └──────────────────────────────────────────────┘ │ -└────────────────────────────────────────────────────┘ -``` - -**Defense in Depth**: 6 layers of isolation (v0.1.1+) -- **Layer 1**: Browser sandbox (built-in) -- **Layer 2**: Extension process (Manifest v3 service worker) -- **Layer 3**: Security layer (input validation, XSS prevention) ← NEW v0.1.1 -- **Layer 4**: WASM sandbox (compile-time memory safety) -- **Layer 5**: Svalinn container (v2.0+, optional) -- **Layer 6**: Vörðr container (v5.0+, full formal verification) - ---- - -## Documentation - -- `README.adoc` - Project overview -- `docs/SEAM-ANALYSIS.adoc` - Integration point analysis -- `docs/ROADMAP.adoc` - Version evolution plan -- `docs/SECURITY-ACCESSIBILITY-CHECKLIST.adoc` - WCAG 2.3 AAA & security compliance ← NEW v0.1.1 -- `docs/SESSION-SUMMARY-20260124-SECURITY-ACCESSIBILITY.md` - Implementation details ← NEW v0.1.1 -- `docs/DEFENSE-LAYERS.adoc` - OSI layer security analysis -- `docs/COMPETITIVE-LANDSCAPE.adoc` - Comparison with existing tools -- `docs/NETWORK-PROTOCOLS.adoc` - IPv6, QUIC, HTTP/3, SPARK integration -- `docs/CONTAINERIZATION-ANALYSIS.adoc` - Svalinn/Vörðr/Cerro Torre integration -- `docs/EPHAPAX-PERFORMANCE.adoc` - Performance benchmarks, Coq proofs -- `docs/EPHAPAX-MIGRATION-STRATEGY.adoc` - Incremental adoption plan -- `STATE.scm` - Current project state -- `META.scm` - Architecture decision records (ADRs) -- `ECOSYSTEM.scm` - Position in hyperpolymath ecosystem - ---- - -## Repository - -**GitHub**: https://github.com/hyperpolymath/algorithm-shield - -**Status**: Early development (v0.1.1), 75% complete -- ✅ Phase 1 (Security & Accessibility) COMPLETE -- 🟡 Phase 2 (Live Testing) In Progress -- 🔜 Phase 3 (v0.5 MVP) Planned - -**License**: MPL-2.0 (Palimpsest-MPL) - ---- - -## Key Insight - -**The membrane operates at every layer - but not every layer needs Ephapax.** - -Use the right tool for each job: -- **ReScript**: User interface (type-safe, functional, React-like) -- **Rust**: FFI, I/O, serialization (mature ecosystem, excellent tooling) -- **Ephapax**: Performance-critical cores (linear types, regions, Coq proofs) - -**80/20 rule**: 20% of code (hot paths) accounts for 80% of runtime. - -Optimize the 20% that matters, keep the 80% simple. - ---- - -## Recent Changes (v0.1.1 - 2026-01-24) - -### Security Hardening ✅ - -**New Security Module** (`dist/popup.js`): -- `Security.sanitizeText()` - Prevents XSS via text injection -- `Security.validateState()` - Type/range/enum validation -- `Security.validateMessage()` - Whitelist-based message filtering -- `Security.sanitizeHTML()` - Removes scripts and event handlers - -**Strengthened CSP**: -``` -default-src 'self'; -script-src 'self' 'wasm-unsafe-eval'; -object-src 'none'; ← Blocks plugins -frame-ancestors 'none'; ← Prevents clickjacking -upgrade-insecure-requests; ← Forces HTTPS -``` - -### Accessibility (WCAG 2.3 AAA) ✅ - -**New Accessibility Module** (`dist/popup.js`): -- Full keyboard navigation (Tab, Arrow keys, Escape) -- Screen reader support (ARIA labels, live regions, semantic HTML) -- Context-sensitive help (tooltips on all controls) -- AAA color contrast (14.6:1 ratio achieved) -- Reduced motion support (`prefers-reduced-motion`) -- High contrast mode (`prefers-contrast: high`) - -**18/18 WCAG 2.3 AAA criteria met.** - -### Seams Progress ✅ - -| Seam | Before | After | Status | -|------|--------|-------|--------| -| Seam 2 (ReScript ↔ WASM) | 80% | 100% | ✅ **CLOSED** | -| Seam 4 (Popup ↔ State) | 80% | 95% | ✅ **SEALED** | -| Seam 1 (ReScript ↔ Browser) | 60% | 75% | ✅ **SMOOTHED** | -| Seam 3 (Content ↔ DOM) | 30% | 75% | 🟡 Improved | - ---- - -_Last updated: 2026-01-24 (v0.1.1)_ diff --git a/algorithm-shield/CODE_OF_CONDUCT.adoc b/algorithm-shield/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..1158bec --- /dev/null +++ b/algorithm-shield/CODE_OF_CONDUCT.adoc @@ -0,0 +1,340 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +Misinformation Defence Platform a harassment-free experience for +everyone, regardless of age, body size, visible or invisible disability, +ethnicity, sex characteristics, gender identity and expression, level of +experience, education, socio-economic status, nationality, personal +appearance, race, caste, colour, religion, or sexual identity and +orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/misinformation-defence-platform/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/algorithm-shield/CODE_OF_CONDUCT.md b/algorithm-shield/CODE_OF_CONDUCT.md deleted file mode 100644 index 4e3044b..0000000 --- a/algorithm-shield/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Misinformation Defence Platform a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/misinformation-defence-platform/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/algorithm-shield/CONTRIBUTING.adoc b/algorithm-shield/CONTRIBUTING.adoc index 596217c..e48f66c 100644 --- a/algorithm-shield/CONTRIBUTING.adoc +++ b/algorithm-shield/CONTRIBUTING.adoc @@ -1,202 +1,111 @@ -= Contributing to Algorithm Shield -:toc: -:toc-placement!: +== Clone the repository -[.lead] -Guidelines for contributing to Algorithm Shield. +git clone +https://github.com/hyperpolymath/misinformation-defence-platform.git cd +misinformation-defence-platform -toc::[] +== Using Nix (recommended for reproducibility) -== Development Setup +nix develop -=== Prerequisites +== Or using toolbox/distrobox -Install the required tools: +toolbox create misinformation-defence-platform-dev toolbox enter +misinformation-defence-platform-dev # Install dependencies manually -[source,bash] ----- -# ReScript compiler (global install) -npm install -g rescript +== Verify setup -# Rust toolchain with WASM target -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -rustup target add wasm32-unknown-unknown +just check # or: cargo check / mix compile / etc. just test # Run test +suite -# wasm-pack (Rust → WASM build tool) -curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh +.... -# Deno (should already be installed per RSR) -curl -fsSL https://deno.land/install.sh | sh ----- +### Repository Structure +.... -=== Clone and Build +misinformation-defence-platform/ ├── src/ # Source code (Perimeter 1-2) +├── lib/ # Library code (Perimeter 1-2) ├── extensions/ # Extensions +(Perimeter 2) ├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling +(Perimeter 2) ├── docs/ # Documentation (Perimeter 3) │ ├── +architecture/ # ADRs, specs (Perimeter 2) │ └── proposals/ # RFCs +(Perimeter 3) ├── examples/ # Examples (Perimeter 3) ├── spec/ # Spec +tests (Perimeter 3) ├── tests/ # Test suite (Perimeter 2-3) ├── +.well-known/ # Protocol files (Perimeter 1-3) ├── .github/ # GitHub +config (Perimeter 1) │ ├── ISSUE_TEMPLATE/ │ └── workflows/ ├── +CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md # This file ├── +GOVERNANCE.md ├── LICENSE ├── MAINTAINERS.md ├── README.adoc ├── +SECURITY.md ├── flake.nix # Nix flake (Perimeter 1) └── Justfile # Task +runner (Perimeter 1) -[source,bash] ----- -# Clone to canonical location (per RSR) -cd ~/Documents/hyperpolymath-repos -git clone git@github.com:hyperpolymath/algorithm-shield.git -cd algorithm-shield +.... -# Build the extension -deno task build +--- -# Or run in development mode (watches ReScript files) -deno task dev ----- +## How to Contribute -=== Load in Chrome +### Reporting Bugs -1. Open `chrome://extensions` -2. Enable "Developer mode" (top-right) -3. Click "Load unpacked" -4. Select `algorithm-shield/dist/` directory +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects -== Project Structure +**When reporting**: -[source] ----- -algorithm-shield/ -├── src/ -│ ├── rescript/ # Core logic (type-safe) -│ │ ├── membrane/ # State orchestrator -│ │ ├── observer/ # Feed analysis -│ │ ├── actuator/ # Controlled interactions -│ │ ├── lens/ # Feed transformations -│ │ └── persona/ # Behavioral shells -│ ├── rust/ # Rule engine (compiles to WASM) -│ │ └── minikaren/ # Logic programming core -│ ├── ui/ # Popup and control panel -│ └── platforms/ # Platform-specific adapters -├── public/ # HTML/CSS/assets -├── scripts/ # Build tooling (Deno) -├── STATE.scm # Current project state -├── META.scm # Architecture decisions -└── ECOSYSTEM.scm # Ecosystem position ----- +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: -== Code Style +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction -=== ReScript +### Suggesting Features -* Follow official https://rescript-lang.org/docs/manual/latest/overview[ReScript style guide] -* Use 2-space indentation -* Prefer pattern matching over if/else -* Use descriptive variable names (per CLAUDE.md) -* Annotate complex types +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to -=== Rust +**When suggesting**: -* Run `cargo fmt` before committing -* Use `cargo clippy` to catch common issues -* Add doc comments for public APIs -* Prefer explicit types for complex closures +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: -=== JavaScript Glue +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects -* Minimal JS - only for browser APIs not yet bound in ReScript -* Follow Deno lint rules -* Add comments explaining why JS is necessary +### Your First Contribution -== Testing +Look for issues labelled: -=== ReScript Tests +- [`good first issue`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/perimeter-3) — Community sandbox scope -[source,bash] ----- -# Run ReScript tests (when implemented) -npx rescript build -with-deps ----- +--- -=== Rust Tests +## Development Workflow -[source,bash] ----- -cd src/rust -cargo test ----- +### Branch Naming +.... -=== Manual Extension Testing +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) -1. Build: `deno task build` -2. Reload extension in Chrome -3. Test on target platform (YouTube, X, etc.) -4. Check browser console for errors -5. Verify activity log +.... -== Commit Guidelines +### Commit Messages -* Use conventional commits format: `type(scope): message` -* Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore` -* Reference issues: `fixes #123` -* Keep commits atomic (one logical change per commit) +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... -Examples: - -[source] ----- -feat(lens): implement Opposition lens transformation -fix(actuator): rate limiter off-by-one error -docs(readme): add installation troubleshooting -refactor(observer): extract platform detection ----- +(): -== Adding a New Platform +{empty}[optional body] -To add support for a new platform (e.g., Instagram): - -1. Create `src/platforms/instagram/` -2. Implement the platform adapter interface: - -[source,rescript] ----- -// src/platforms/instagram/InstagramAdapter.res -let detectPlatform = (url: string): bool => { - url->String.includes("instagram.com") -} - -let extractSignals = (document: Dom.document): array => { - // Platform-specific DOM scraping - [] -} ----- - -3. Register in platform registry -4. Test on live Instagram feed -5. Document DOM selectors and quirks - -== Adding a New Lens - -To add a new lens: - -1. Add variant to `Membrane.State.lensType` -2. Implement `applyXLens` in `Lens.res` -3. Add lens card to `popup.html` -4. Test transformation logic -5. Document lens behavior in README - -== Adding a New Persona - -To add a new persona: - -1. Define in `Persona.PersonaDefinition` -2. Specify behavioral traits (interests, avoidances, click probability) -3. Add persona card to `popup.html` -4. Test behavioral alignment -5. Document persona in README - -== Pull Request Process - -1. Fork the repository -2. Create feature branch: `git checkout -b feat/my-feature` -3. Make changes and test thoroughly -4. Update STATE.scm if significant progress -5. Update documentation if adding features -6. Submit PR with clear description -7. Reference related issues - -== License - -All contributions are licensed under MPL-2.0. - -By contributing, you agree that your contributions will be licensed under the same terms. +{empty}[optional footer] diff --git a/algorithm-shield/CONTRIBUTING.md b/algorithm-shield/CONTRIBUTING.md deleted file mode 100644 index 7e4af22..0000000 --- a/algorithm-shield/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/misinformation-defence-platform.git -cd misinformation-defence-platform - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create misinformation-defence-platform-dev -toolbox enter misinformation-defence-platform-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -misinformation-defence-platform/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/algorithm-shield/SECURITY.adoc b/algorithm-shield/SECURITY.adoc new file mode 100644 index 0000000..c390ace --- /dev/null +++ b/algorithm-shield/SECURITY.adoc @@ -0,0 +1,70 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|0.x.x |:white_check_mark: +|=== + +=== Reporting a Vulnerability + +*DO NOT* open a public issue for security vulnerabilities. + +Instead, email security reports to: *security@hyperpolymath.org* + +Include: + +[arabic] +. Description of the vulnerability +. Steps to reproduce +. Potential impact +. Suggested fix (if you have one) + +We will respond within 48 hours and work with you to understand and +address the issue. + +=== Security Considerations + +Algorithm Shield operates with sensitive permissions (content script +injection, storage, active tab). + +==== What We Do + +* ✅ All data stays local (chrome.storage.local) +* ✅ No external network requests (except user-initiated membrane +breaches) +* ✅ Rate limiting on all automated actions +* ✅ User consent required for sensitive operations +* ✅ Transparent activity logging +* ✅ Source code is public and auditable + +==== What We Don’t Do + +* ❌ Never exfiltrate user data +* ❌ Never track users +* ❌ Never communicate with external servers +* ❌ Never modify pages without user awareness +* ❌ Never execute arbitrary code from external sources + +=== Known Limitations + +[arabic] +. *Platform DOM Changes*: If a platform changes their DOM structure, +extraction may break +. *Rate Limits*: Extensions can be detected by platform-side rate +limiting +. *WASM Security*: WASM module is compiled from Rust, but could +theoretically be exploited + +=== Responsible Disclosure + +If you discover a security issue: + +[arabic] +. Email us (don’t open a public issue) +. Wait for our response (48 hours) +. Work with us on a fix +. We’ll credit you in the release notes (if you want) +. Coordinated public disclosure after fix is released diff --git a/algorithm-shield/SECURITY.md b/algorithm-shield/SECURITY.md deleted file mode 100644 index 568ee44..0000000 --- a/algorithm-shield/SECURITY.md +++ /dev/null @@ -1,59 +0,0 @@ -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 0.x.x | :white_check_mark: | - -## Reporting a Vulnerability - -**DO NOT** open a public issue for security vulnerabilities. - -Instead, email security reports to: **security@hyperpolymath.org** - -Include: - -1. Description of the vulnerability -2. Steps to reproduce -3. Potential impact -4. Suggested fix (if you have one) - -We will respond within 48 hours and work with you to understand and address the issue. - -## Security Considerations - -Algorithm Shield operates with sensitive permissions (content script injection, storage, active tab). - -### What We Do - -- ✅ All data stays local (chrome.storage.local) -- ✅ No external network requests (except user-initiated membrane breaches) -- ✅ Rate limiting on all automated actions -- ✅ User consent required for sensitive operations -- ✅ Transparent activity logging -- ✅ Source code is public and auditable - -### What We Don't Do - -- ❌ Never exfiltrate user data -- ❌ Never track users -- ❌ Never communicate with external servers -- ❌ Never modify pages without user awareness -- ❌ Never execute arbitrary code from external sources - -## Known Limitations - -1. **Platform DOM Changes**: If a platform changes their DOM structure, extraction may break -2. **Rate Limits**: Extensions can be detected by platform-side rate limiting -3. **WASM Security**: WASM module is compiled from Rust, but could theoretically be exploited - -## Responsible Disclosure - -If you discover a security issue: - -1. Email us (don't open a public issue) -2. Wait for our response (48 hours) -3. Work with us on a fix -4. We'll credit you in the release notes (if you want) -5. Coordinated public disclosure after fix is released diff --git a/algorithm-shield/docs/SEAM-SUMMARY.adoc b/algorithm-shield/docs/SEAM-SUMMARY.adoc new file mode 100644 index 0000000..ae44076 --- /dev/null +++ b/algorithm-shield/docs/SEAM-SUMMARY.adoc @@ -0,0 +1,167 @@ +== Algorithm Shield - Seam Analysis Summary + +Quick reference for critical integration points. + +=== 10 Critical Seams (Ranked by Risk) + +[width="100%",cols="9%,13%,13%,31%,34%",options="header",] +|=== +|# |Seam |Risk |Why Critical |Must Close By +|*3* |Content ↔ DOM |🔴 CRITICAL |Platforms change DOM constantly, +breaks everything |v0.5 + +|*6* |Actuator ↔ Detection |🔴 CRITICAL |Bot detection = instant +failure, ethical concerns |v0.5 + +|*2* |ReScript ↔ WASM |🟠 HIGH |Cross-language boundary, async loading, +size |v0.5 + +|*10* |Cross-Platform |🟠 HIGH |Fundamental architecture decision +affects all future work |v1.0 + +|*1* |ReScript ↔ Browser |🟡 MEDIUM |Type safety gap, but APIs are +stable |v0.5 + +|*4* |Popup ↔ State |🟡 MEDIUM |State drift, but standard patterns exist +|v0.5 + +|*5* |Lens ↔ Rendering |🟡 MEDIUM |Performance risk, but DOM APIs stable +|v0.5 + +|*8* |Persona ↔ Rules |🟡 MEDIUM |Behavioral coherence, needs tuning +|v1.0 + +|*9* |Updates ↔ Migration |🟡 MEDIUM |Data loss risk, but solvable |v1.0 + +|*7* |Log ↔ Narrative |🟢 LOW |UX problem, not technical blocker |v1.0 +|=== + +=== Critical Path to v0.5 + +.... +Week 1-2: Build Infrastructure + └─ Close Seam 2: WASM builds, loads, responds + └─ Close Seam 1: Browser API bindings written + └─ Extension loads in Chrome + +Week 3-4: YouTube Observer + └─ Close Seam 3: YouTube DOM mapped, signals extracted + └─ Feed diversity calculation works + └─ Popup displays bubble state + +Week 5-6: Membrane Breach + └─ Close Seam 6: Human-like timing implemented + └─ Random Walk generates URLs + └─ Breach opens tabs without detection + +Week 7-8: Polish + └─ Activity log functional + └─ State persistence works + └─ User testing (5-10 people) +.... + +=== Version Evolution (Feature Matrix) + +[cols=",,,,,,",options="header",] +|=== +|Feature |v0.1 |v0.5 |v1.0 |v2.0 |v5.0 |v10.0 +|*Platforms* |0 |1 |3 |5+ |10+ |Any +|*Lenses* |0 |1 |5 |10+ |∞ |Protocol +|*Personas* |0 |0 |3 |∞ |Federated |Distributed +|*Rules* |Code |Hard |Custom |Market |ML |Verified +|*Privacy* |Local |Local |Local |E2E |Diff-Private |Zero-K +|=== + +=== Immediate Next Steps + +[source,bash] +---- +# 1. Install tools +npm install -g rescript +curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh + +# 2. Test compilation +cd ~/Documents/hyperpolymath-repos/algorithm-shield +npx rescript build + +# 3. Build WASM +cd src/rust +wasm-pack build --target web --out-dir ../../dist/wasm + +# 4. Create icons (placeholder) +# Use any image tool to create 16x16, 48x48, 128x128 PNG + +# 5. Load extension +# Chrome → chrome://extensions → Load unpacked → select dist/ +---- + +=== Risk Mitigation Strategy + +==== Platform Resistance (Seam 3, 6) + +* *v0.5*: Conservative approach, minimal automation +* *v1.0*: Legal review before public release +* *v2.0+*: Platform cooperation API (carrot, not stick) + +==== Maintenance Burden (Seam 3) + +* *v0.5*: One platform only (YouTube) +* *v1.0*: Version selectors, graceful degradation +* *v5.0*: Community-maintained adapters +* *v10.0*: Platform-provided APIs (cooperation) + +==== User Adoption (All seams) + +* *v0.5*: 10 testers (feedback loop) +* *v1.0*: 1,000 users (validation) +* *v5.0*: 100,000 users (network effects) +* *v10.0*: 1M+ users (ecosystem standard) + +=== Long-Term Bets + +[arabic] +. *Personas become portable identity* (v2.0) +* Cryptographically signed (Januskey) +* Sync across devices +* Marketplace emerges +. *Bubble map becomes collective tool* (v5.0) +* Anonymized sharing +* Crowdsourced topology +* Community lenses +. *Counter-algorithms become browser feature* (v10.0) +* W3C standard +* Browser-native +* Platform cooperation + +=== Open Questions + +==== Technical + +* [ ] Can WASM stay under 200KB? (v0.5 test) +* [ ] Will cross-platform abstraction hold? (v1.0 test) +* [ ] Can we federate without leaking privacy? (v5.0 research) + +==== Legal/Ethical + +* [ ] Do we need ToS compliance review? (Before v1.0) +* [ ] Is this "`unauthorized access`"? (Legal consult) +* [ ] What if platforms explicitly ban this? (Risk mitigation) + +==== Social + +* [ ] Will users adopt polymorphism? (UX research, v0.5-1.0) +* [ ] Is there demand for persona marketplace? (v2.0 pivot point) +* [ ] Will community contribute lenses? (v5.0 assumption test) + +=== Files to Read + +* *Full Analysis*: link:SEAM-ANALYSIS.adoc[docs/SEAM-ANALYSIS.adoc] +* *Version Plan*: link:ROADMAP.adoc[docs/ROADMAP.adoc] +* *Current State*: link:../STATE.scm[STATE.scm] +* *Decisions*: link:../META.scm[META.scm] +* *Position*: link:../ECOSYSTEM.scm[ECOSYSTEM.scm] + +''''' + +*Status*: Scaffold complete, seams identified, path mapped *Next*: Close +seam 2 (WASM integration) *Goal*: v0.5 by 2026-03-15 diff --git a/algorithm-shield/docs/SEAM-SUMMARY.md b/algorithm-shield/docs/SEAM-SUMMARY.md deleted file mode 100644 index 66a519a..0000000 --- a/algorithm-shield/docs/SEAM-SUMMARY.md +++ /dev/null @@ -1,141 +0,0 @@ -# Algorithm Shield - Seam Analysis Summary - -Quick reference for critical integration points. - -## 10 Critical Seams (Ranked by Risk) - -| # | Seam | Risk | Why Critical | Must Close By | -|---|------|------|--------------|---------------| -| **3** | Content ↔ DOM | 🔴 CRITICAL | Platforms change DOM constantly, breaks everything | v0.5 | -| **6** | Actuator ↔ Detection | 🔴 CRITICAL | Bot detection = instant failure, ethical concerns | v0.5 | -| **2** | ReScript ↔ WASM | 🟠 HIGH | Cross-language boundary, async loading, size | v0.5 | -| **10** | Cross-Platform | 🟠 HIGH | Fundamental architecture decision affects all future work | v1.0 | -| **1** | ReScript ↔ Browser | 🟡 MEDIUM | Type safety gap, but APIs are stable | v0.5 | -| **4** | Popup ↔ State | 🟡 MEDIUM | State drift, but standard patterns exist | v0.5 | -| **5** | Lens ↔ Rendering | 🟡 MEDIUM | Performance risk, but DOM APIs stable | v0.5 | -| **8** | Persona ↔ Rules | 🟡 MEDIUM | Behavioral coherence, needs tuning | v1.0 | -| **9** | Updates ↔ Migration | 🟡 MEDIUM | Data loss risk, but solvable | v1.0 | -| **7** | Log ↔ Narrative | 🟢 LOW | UX problem, not technical blocker | v1.0 | - -## Critical Path to v0.5 - -``` -Week 1-2: Build Infrastructure - └─ Close Seam 2: WASM builds, loads, responds - └─ Close Seam 1: Browser API bindings written - └─ Extension loads in Chrome - -Week 3-4: YouTube Observer - └─ Close Seam 3: YouTube DOM mapped, signals extracted - └─ Feed diversity calculation works - └─ Popup displays bubble state - -Week 5-6: Membrane Breach - └─ Close Seam 6: Human-like timing implemented - └─ Random Walk generates URLs - └─ Breach opens tabs without detection - -Week 7-8: Polish - └─ Activity log functional - └─ State persistence works - └─ User testing (5-10 people) -``` - -## Version Evolution (Feature Matrix) - -| Feature | v0.1 | v0.5 | v1.0 | v2.0 | v5.0 | v10.0 | -|---------|------|------|------|------|------|-------| -| **Platforms** | 0 | 1 | 3 | 5+ | 10+ | Any | -| **Lenses** | 0 | 1 | 5 | 10+ | ∞ | Protocol | -| **Personas** | 0 | 0 | 3 | ∞ | Federated | Distributed | -| **Rules** | Code | Hard | Custom | Market | ML | Verified | -| **Privacy** | Local | Local | Local | E2E | Diff-Private | Zero-K | - -## Immediate Next Steps - -```bash -# 1. Install tools -npm install -g rescript -curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh - -# 2. Test compilation -cd ~/Documents/hyperpolymath-repos/algorithm-shield -npx rescript build - -# 3. Build WASM -cd src/rust -wasm-pack build --target web --out-dir ../../dist/wasm - -# 4. Create icons (placeholder) -# Use any image tool to create 16x16, 48x48, 128x128 PNG - -# 5. Load extension -# Chrome → chrome://extensions → Load unpacked → select dist/ -``` - -## Risk Mitigation Strategy - -### Platform Resistance (Seam 3, 6) -- **v0.5**: Conservative approach, minimal automation -- **v1.0**: Legal review before public release -- **v2.0+**: Platform cooperation API (carrot, not stick) - -### Maintenance Burden (Seam 3) -- **v0.5**: One platform only (YouTube) -- **v1.0**: Version selectors, graceful degradation -- **v5.0**: Community-maintained adapters -- **v10.0**: Platform-provided APIs (cooperation) - -### User Adoption (All seams) -- **v0.5**: 10 testers (feedback loop) -- **v1.0**: 1,000 users (validation) -- **v5.0**: 100,000 users (network effects) -- **v10.0**: 1M+ users (ecosystem standard) - -## Long-Term Bets - -1. **Personas become portable identity** (v2.0) - - Cryptographically signed (Januskey) - - Sync across devices - - Marketplace emerges - -2. **Bubble map becomes collective tool** (v5.0) - - Anonymized sharing - - Crowdsourced topology - - Community lenses - -3. **Counter-algorithms become browser feature** (v10.0) - - W3C standard - - Browser-native - - Platform cooperation - -## Open Questions - -### Technical -- [ ] Can WASM stay under 200KB? (v0.5 test) -- [ ] Will cross-platform abstraction hold? (v1.0 test) -- [ ] Can we federate without leaking privacy? (v5.0 research) - -### Legal/Ethical -- [ ] Do we need ToS compliance review? (Before v1.0) -- [ ] Is this "unauthorized access"? (Legal consult) -- [ ] What if platforms explicitly ban this? (Risk mitigation) - -### Social -- [ ] Will users adopt polymorphism? (UX research, v0.5-1.0) -- [ ] Is there demand for persona marketplace? (v2.0 pivot point) -- [ ] Will community contribute lenses? (v5.0 assumption test) - -## Files to Read - -- **Full Analysis**: [docs/SEAM-ANALYSIS.adoc](SEAM-ANALYSIS.adoc) -- **Version Plan**: [docs/ROADMAP.adoc](ROADMAP.adoc) -- **Current State**: [STATE.scm](../STATE.scm) -- **Decisions**: [META.scm](../META.scm) -- **Position**: [ECOSYSTEM.scm](../ECOSYSTEM.scm) - ---- - -**Status**: Scaffold complete, seams identified, path mapped -**Next**: Close seam 2 (WASM integration) -**Goal**: v0.5 by 2026-03-15 diff --git a/algorithm-shield/docs/SESSION-SUMMARY-20260124-SECURITY-ACCESSIBILITY.adoc b/algorithm-shield/docs/SESSION-SUMMARY-20260124-SECURITY-ACCESSIBILITY.adoc new file mode 100644 index 0000000..01c3e5c --- /dev/null +++ b/algorithm-shield/docs/SESSION-SUMMARY-20260124-SECURITY-ACCESSIBILITY.adoc @@ -0,0 +1,476 @@ +== Session Summary: Security & Accessibility Implementation + +*Date:* 2026-01-24 *Duration:* ~90 minutes *Version:* v0.1.0 → v0.1.1 + +=== Executive Summary + +Implemented comprehensive *WCAG 2.3 AAA accessibility* and *security +hardening* for Algorithm Shield browser extension, bringing Phase 1 +(CRYPTOGRAPHIC-SUITE.adoc) to completion. + +*Overall Progress:* 65% → 75% + +''''' + +=== 1. Security Hardening (Task #8) ✅ + +==== Input Validation & Sanitization + +*Implemented Security Module* (`+popup.js+`): + +[arabic] +. *Text Sanitization* - `+Security.sanitizeText()+` +* Prevents XSS injection via text content +* Safe for display in innerHTML/textContent contexts +. *State Validation* - `+Security.validateState()+` +* Type checking: mode (string), thickness (number), isPaused (boolean) +* Range validation: thickness must be 0.0-1.0 +* Enum validation: mode ∈ \{normal, persona}, lenses ∈ \{opposition, +random-walk, …} +* Protects against storage corruption/injection +. *Message Validation* - `+Security.validateMessage()+` +* Whitelist-based: only 4 allowed message types +* Prevents arbitrary command injection from content scripts +. *HTML Sanitization* - `+Security.sanitizeHTML()+` +* Removes `+' } +}) +// Expected: Script tag escaped, no alert ✅ + +// Test 2: Invalid state +chrome.storage.local.set({ + shieldState: { membraneThickness: 999 } +}) +// Expected: State rejected, defaults restored ✅ + +// Test 3: Malicious message +chrome.runtime.sendMessage({ + type: 'EVIL_ACTION', + payload: '' +}) +// Expected: Message rejected, console warning ✅ +---- + +==== Accessibility Testing + +*Automated:* 1. Run *axe DevTools* - expect 0 violations 2. Run *WAVE* - +expect AAA compliance 3. Run *Lighthouse* - expect 100/100 accessibility +score + +*Manual:* 1. *Keyboard-only navigation* (unplug mouse) - Tab through all +controls ✅ - Activate with Enter/Space ✅ - Navigate grids with arrow +keys ✅ - Dismiss tooltips with Escape ✅ + +[arabic, start=2] +. *Screen reader testing* (NVDA/JAWS/VoiceOver) +* All content announced ✅ +* State changes announced ✅ +* Tooltips read on focus ✅ +. *Zoom testing* +* 200% zoom - all content readable ✅ +* 400% zoom - no horizontal scroll ✅ +. *High contrast mode* +* Windows High Contrast ✅ +* All controls visible ✅ + +''''' + +=== 6. Phase 1 (CRYPTOGRAPHIC-SUITE.adoc) Status + +==== ✅ COMPLETED + +*Phase 1: Accessibility (v1.0 - IMMEDIATE)* + +* [x] ARIA labels on all interactive elements +* [x] Keyboard navigation (tab order, shortcuts, focus management) +* [x] Screen reader testing preparation (markup ready) +* [x] High contrast mode support +* [x] Respect `+prefers-reduced-motion+` +* [x] Scalable text (200% zoom support) +* [x] Color contrast: 7:1 minimum (AAA level) +* [x] Focus indicators: 3px minimum, high contrast +* [x] Semantic HTML (proper heading hierarchy) +* [x] Live regions for dynamic content updates +* [x] Skip links for keyboard users +* [x] Alternative text for all icons/images (aria-hidden on decorative) +* [x] Help text / tooltips explaining all controls +* [x] Consistent patterns (no surprises) +* [x] Plain language (Grade 8 readability) + +==== 🔜 NEXT (Phase 2: .aep File Integrity - v1.5) + +* [ ] Implement SHAKE3-512 hashing +* [ ] Generate user-friendly fingerprints (Base32 → wordlist) +* [ ] Update .aep format with integrity fields +* [ ] Verification on import + +''''' + +=== 7. Next Steps + +==== Immediate (v0.1.1 → v0.5) + +[arabic] +. *Test on Live Sites* (Task #4 - in progress) +* Load extension in Chrome +* Test Bing (working baseline) +* Test Google, YouTube, Twitter +. *Documentation Updates* (Tasks #5, #6 - pending) +* Update README.adoc with security/accessibility features +* Update ROADMAP with v0.1.1 milestone +* Update ARCHITECTURE with Security module +. *Seams Polishing* +* *Seam 7:* Activity log narrative generation +* *Seam 8:* Persona ↔ Rules integration +* *Seam 9:* State migration strategy +* *Seam 10:* Cross-platform abstraction validation + +==== Medium-term (v0.5 - Mar 2026) + +[arabic] +. *Build & Test* +* Compile ReScript to production +* Build extension bundle +* User testing with 5-10 people +. *Remaining Seams* +* Close Seam 6 (bot detection evasion) +* Close Seam 3 (platform adapter completion) +. *Quality Gates* +* Screen reader testing (NVDA, JAWS, VoiceOver) +* axe DevTools scan (0 violations) +* Security audit (self-review) + +''''' + +=== 8. Files Changed Summary + +==== Created + +* `+docs/SECURITY-ACCESSIBILITY-CHECKLIST.adoc+` (1,200 lines) +* `+dist/popup.html+` (220 lines, ARIA-rich) +* `+dist/popup.js+` (435 lines, Security + Accessibility modules) +* `+dist/popup.css+` (466 lines, AAA compliant) +* `+dist/manifest.json+` (tightened CSP) + +==== Metrics + +* *Lines Added:* ~2,300 +* *Security Functions:* 4 (sanitizeText, validateState, validateMessage, +sanitizeHTML) +* *Accessibility Functions:* 5 (keyboard nav, tooltips, ARIA updates, +announcements) +* *WCAG AAA Criteria Met:* 18/18 applicable +* *Attack Vectors Mitigated:* 6 +* *Seams Improved:* 2 (closed), 2 (smoothed) + +''''' + +=== 9. Lessons Learned + +==== Security + +* *Validate Everything:* State, messages, HTML - trust nothing from +storage or messages +* *CSP is Essential:* Tighten incrementally, test thoroughly +* *Permissions Minimalism:* Only request what you absolutely need +* *Document Justifications:* Every permission should have a clear reason + +==== Accessibility + +* *ARIA is Not Optional:* Screen readers rely on semantic markup +* *Test Early:* Keyboard-only testing reveals UX issues +* *Help Text Matters:* Tooltips make complex UIs approachable +* *Contrast is Crucial:* AAA (7:1) is noticeably better than AA (4.5:1) +* *Motion Sensitivity:* `+prefers-reduced-motion+` is widely used + +==== Development + +* *Incremental Progress:* Small, tested changes beat big rewrites +* *Documentation While Fresh:* Write docs immediately after +implementation +* *Checkpoint Files:* STATE.scm keeps context across sessions + +''''' + +=== 10. Conclusion + +*Phase 1 of CRYPTOGRAPHIC-SUITE.adoc (Accessibility + Security) is +COMPLETE.* + +Algorithm Shield now has: - ✅ *WCAG 2.3 AAA* accessibility (18/18 +criteria met) - ✅ *Comprehensive security hardening* (input validation, +CSP, attack surface minimization) - ✅ *Production-ready UI* (semantic, +accessible, secure) - ✅ *Smooth seams* (Seam 2 closed, Seam 4 sealed, +Seam 1 & 3 improved) + +*Ready for:* - Screen reader testing - Live site testing - User feedback +(5-10 people) + +*Next Phase:* - Documentation updates (README, ROADMAP, ARCHITECTURE) - +Live testing on platforms (Google, YouTube, Twitter) - Seam 7-10 +resolution (v0.5 milestone) + +''''' + +*Committed:* 2026-01-24, commit `+69927c2+` *Tasks Completed:* #2 +(Accessibility), #8 (Security) *Overall Progress:* 65% → 75% *Phase 1 +Status:* ✅ COMPLETE diff --git a/algorithm-shield/docs/SESSION-SUMMARY-20260124-SECURITY-ACCESSIBILITY.md b/algorithm-shield/docs/SESSION-SUMMARY-20260124-SECURITY-ACCESSIBILITY.md deleted file mode 100644 index 620979c..0000000 --- a/algorithm-shield/docs/SESSION-SUMMARY-20260124-SECURITY-ACCESSIBILITY.md +++ /dev/null @@ -1,473 +0,0 @@ -# Session Summary: Security & Accessibility Implementation -**Date:** 2026-01-24 -**Duration:** ~90 minutes -**Version:** v0.1.0 → v0.1.1 - -## Executive Summary - -Implemented comprehensive **WCAG 2.3 AAA accessibility** and **security hardening** for Algorithm Shield browser extension, bringing Phase 1 (CRYPTOGRAPHIC-SUITE.adoc) to completion. - -**Overall Progress:** 65% → 75% - ---- - -## 1. Security Hardening (Task #8) ✅ - -### Input Validation & Sanitization - -**Implemented Security Module** (`popup.js`): - -1. **Text Sanitization** - `Security.sanitizeText()` - - Prevents XSS injection via text content - - Safe for display in innerHTML/textContent contexts - -2. **State Validation** - `Security.validateState()` - - Type checking: mode (string), thickness (number), isPaused (boolean) - - Range validation: thickness must be 0.0-1.0 - - Enum validation: mode ∈ {normal, persona}, lenses ∈ {opposition, random-walk, ...} - - Protects against storage corruption/injection - -3. **Message Validation** - `Security.validateMessage()` - - Whitelist-based: only 4 allowed message types - - Prevents arbitrary command injection from content scripts - -4. **HTML Sanitization** - `Security.sanitizeHTML()` - - Removes `' } -}) -// Expected: Script tag escaped, no alert ✅ - -// Test 2: Invalid state -chrome.storage.local.set({ - shieldState: { membraneThickness: 999 } -}) -// Expected: State rejected, defaults restored ✅ - -// Test 3: Malicious message -chrome.runtime.sendMessage({ - type: 'EVIL_ACTION', - payload: '' -}) -// Expected: Message rejected, console warning ✅ -``` - -### Accessibility Testing - -**Automated:** -1. Run **axe DevTools** - expect 0 violations -2. Run **WAVE** - expect AAA compliance -3. Run **Lighthouse** - expect 100/100 accessibility score - -**Manual:** -1. **Keyboard-only navigation** (unplug mouse) - - Tab through all controls ✅ - - Activate with Enter/Space ✅ - - Navigate grids with arrow keys ✅ - - Dismiss tooltips with Escape ✅ - -2. **Screen reader testing** (NVDA/JAWS/VoiceOver) - - All content announced ✅ - - State changes announced ✅ - - Tooltips read on focus ✅ - -3. **Zoom testing** - - 200% zoom - all content readable ✅ - - 400% zoom - no horizontal scroll ✅ - -4. **High contrast mode** - - Windows High Contrast ✅ - - All controls visible ✅ - ---- - -## 6. Phase 1 (CRYPTOGRAPHIC-SUITE.adoc) Status - -### ✅ COMPLETED - -**Phase 1: Accessibility (v1.0 - IMMEDIATE)** - -- [x] ARIA labels on all interactive elements -- [x] Keyboard navigation (tab order, shortcuts, focus management) -- [x] Screen reader testing preparation (markup ready) -- [x] High contrast mode support -- [x] Respect `prefers-reduced-motion` -- [x] Scalable text (200% zoom support) -- [x] Color contrast: 7:1 minimum (AAA level) -- [x] Focus indicators: 3px minimum, high contrast -- [x] Semantic HTML (proper heading hierarchy) -- [x] Live regions for dynamic content updates -- [x] Skip links for keyboard users -- [x] Alternative text for all icons/images (aria-hidden on decorative) -- [x] Help text / tooltips explaining all controls -- [x] Consistent patterns (no surprises) -- [x] Plain language (Grade 8 readability) - -### 🔜 NEXT (Phase 2: .aep File Integrity - v1.5) - -- [ ] Implement SHAKE3-512 hashing -- [ ] Generate user-friendly fingerprints (Base32 → wordlist) -- [ ] Update .aep format with integrity fields -- [ ] Verification on import - ---- - -## 7. Next Steps - -### Immediate (v0.1.1 → v0.5) - -1. **Test on Live Sites** (Task #4 - in progress) - - Load extension in Chrome - - Test Bing (working baseline) - - Test Google, YouTube, Twitter - -2. **Documentation Updates** (Tasks #5, #6 - pending) - - Update README.adoc with security/accessibility features - - Update ROADMAP with v0.1.1 milestone - - Update ARCHITECTURE with Security module - -3. **Seams Polishing** - - **Seam 7:** Activity log narrative generation - - **Seam 8:** Persona ↔ Rules integration - - **Seam 9:** State migration strategy - - **Seam 10:** Cross-platform abstraction validation - -### Medium-term (v0.5 - Mar 2026) - -1. **Build & Test** - - Compile ReScript to production - - Build extension bundle - - User testing with 5-10 people - -2. **Remaining Seams** - - Close Seam 6 (bot detection evasion) - - Close Seam 3 (platform adapter completion) - -3. **Quality Gates** - - Screen reader testing (NVDA, JAWS, VoiceOver) - - axe DevTools scan (0 violations) - - Security audit (self-review) - ---- - -## 8. Files Changed Summary - -### Created -- `docs/SECURITY-ACCESSIBILITY-CHECKLIST.adoc` (1,200 lines) -- `dist/popup.html` (220 lines, ARIA-rich) -- `dist/popup.js` (435 lines, Security + Accessibility modules) -- `dist/popup.css` (466 lines, AAA compliant) -- `dist/manifest.json` (tightened CSP) - -### Metrics -- **Lines Added:** ~2,300 -- **Security Functions:** 4 (sanitizeText, validateState, validateMessage, sanitizeHTML) -- **Accessibility Functions:** 5 (keyboard nav, tooltips, ARIA updates, announcements) -- **WCAG AAA Criteria Met:** 18/18 applicable -- **Attack Vectors Mitigated:** 6 -- **Seams Improved:** 2 (closed), 2 (smoothed) - ---- - -## 9. Lessons Learned - -### Security -- **Validate Everything:** State, messages, HTML - trust nothing from storage or messages -- **CSP is Essential:** Tighten incrementally, test thoroughly -- **Permissions Minimalism:** Only request what you absolutely need -- **Document Justifications:** Every permission should have a clear reason - -### Accessibility -- **ARIA is Not Optional:** Screen readers rely on semantic markup -- **Test Early:** Keyboard-only testing reveals UX issues -- **Help Text Matters:** Tooltips make complex UIs approachable -- **Contrast is Crucial:** AAA (7:1) is noticeably better than AA (4.5:1) -- **Motion Sensitivity:** `prefers-reduced-motion` is widely used - -### Development -- **Incremental Progress:** Small, tested changes beat big rewrites -- **Documentation While Fresh:** Write docs immediately after implementation -- **Checkpoint Files:** STATE.scm keeps context across sessions - ---- - -## 10. Conclusion - -**Phase 1 of CRYPTOGRAPHIC-SUITE.adoc (Accessibility + Security) is COMPLETE.** - -Algorithm Shield now has: -- ✅ **WCAG 2.3 AAA** accessibility (18/18 criteria met) -- ✅ **Comprehensive security hardening** (input validation, CSP, attack surface minimization) -- ✅ **Production-ready UI** (semantic, accessible, secure) -- ✅ **Smooth seams** (Seam 2 closed, Seam 4 sealed, Seam 1 & 3 improved) - -**Ready for:** -- Screen reader testing -- Live site testing -- User feedback (5-10 people) - -**Next Phase:** -- Documentation updates (README, ROADMAP, ARCHITECTURE) -- Live testing on platforms (Google, YouTube, Twitter) -- Seam 7-10 resolution (v0.5 milestone) - ---- - -**Committed:** 2026-01-24, commit `69927c2` -**Tasks Completed:** #2 (Accessibility), #8 (Security) -**Overall Progress:** 65% → 75% -**Phase 1 Status:** ✅ COMPLETE diff --git a/algorithm-shield/docs/TEST-RESULTS-2026-01-24.adoc b/algorithm-shield/docs/TEST-RESULTS-2026-01-24.adoc new file mode 100644 index 0000000..987aace --- /dev/null +++ b/algorithm-shield/docs/TEST-RESULTS-2026-01-24.adoc @@ -0,0 +1,177 @@ +== Algorithm Shield - Test Results + +*Date*: 2026-01-24 *Version*: 0.1.0 *Browser*: Microsoft Edge Dev +(Chromium 140.0.0.0) *Platform*: Linux (Fedora) + +=== Executive Summary + +✅ *ALL CORE TESTS PASSED* - Extension is fully functional and ready for +feature implementation. + +=== Test Results + +==== Test 1: Extension Loading ✅ PASS + +*Action*: Loaded unpacked extension from +`+~/Documents/hyperpolymath-repos/algorithm-shield/dist/+` + +*Issue encountered*: - Initial manifest had unrecognized keys +`+_license+` and `+_copyright+` - Chrome/Edge manifest v3 doesn’t +support custom fields starting with `+_+` + +*Fix applied*: - Removed `+_license+` and `+_copyright+` from +manifest.json - Extension loaded successfully after fix + +*Result*: Extension loaded without errors, assigned ID +`+elpkeefehideemhdinnhdkbiignknacm+` + +''''' + +==== Test 2: Service Worker Activation ✅ PASS + +*Action*: Clicked "`service worker`" link in extension details + +*Observed*: - Console showed: +`+🛡️ Algorithm Shield background worker active+` - Service worker +status: *Active* (green indicator) - No errors in console - Storage +initialization completed successfully + +*Result*: Background script running correctly + +''''' + +==== Test 3: Popup UI Display ✅ PASS + +*Action*: Clicked extension icon in toolbar + +*Observed*: - Popup window opened (300x400px as designed) - HTML/CSS +rendered correctly - All UI elements displayed properly - Icons showed +correctly (shield + membrane design) - No console errors in popup +DevTools + +*Result*: UI fully functional + +''''' + +==== Test 4: WASM Module Loading ✅ PASS + +*Action*: Checked for WASM loading in Network tab and console + +*Observed*: - No WASM loading errors appeared in console - Storage API +test passed (state persisting correctly) - WASM file accessible at +`+dist/pkg/algorithm_shield_engine_bg.wasm+` (181KB) + +*Result*: WASM integration ready (not yet wired to UI, as expected at +v0.1) + +''''' + +==== Test 5: Content Script Injection ✅ PASS + +*Action*: Navigated to YouTube.com and checked console + +*Observed*: + +.... +🛡️ Algorithm Shield active +👁️ Observing feed... +.... + +*Also observed* (NOT errors from Algorithm Shield): - Multiple +`+ERR_BLOCKED_BY_CLIENT+` messages from uBlock Origin ad blocker - +YouTube tracking/analytics requests blocked by ad blocker - Google +DoubleClick ads blocked - Standard YouTube framework warnings (Polymer, +storage permissions) + +*Result*: Content script successfully injected and running on YouTube + +''''' + +=== Issues Found + +==== Issue #1: Manifest Custom Fields ✅ FIXED + +* *Severity*: Low (non-blocking warning) +* *Description*: Manifest contained `+_license+` and `+_copyright+` +fields not recognized by Chrome +* *Fix*: Removed custom fields from both `+dist/manifest.json+` and +source `+manifest.json+` +* *Status*: Resolved + +''''' + +=== Known Limitations (Expected at v0.1) + +These are NOT bugs - they’re features not yet implemented: + +[arabic] +. *ReScript code not compiled* - Using JS placeholders currently +. *WASM not wired to UI* - Module loads but not yet connected to +popup/content scripts +. *Platform adapters stubbed* - YouTube DOM extraction scaffolded but +not fully implemented +. *Lens/Persona logic not connected* - UI buttons present but actions +not wired to actual lens implementations +. *Feed analysis not implemented* - "`Observing feed…`" message appears +but actual analysis pending + +*All expected* - these are the features we’re building next! + +''''' + +=== Performance Metrics + +[cols=",,,",options="header",] +|=== +|Metric |Value |Target |Status +|WASM size |181 KB |< 500 KB |✅ Well under target +|Extension load time |< 1s |< 2s |✅ Fast +|Memory usage (idle) |~15 MB |< 50 MB |✅ Efficient +|Content script inject |Immediate |< 500ms |✅ Fast +|=== + +''''' + +=== Browser Compatibility + +[cols=",,",options="header",] +|=== +|Browser |Version |Status +|Edge Dev |140.0.0.0 |✅ Fully compatible +|Chrome |Not tested |Expected compatible (same Chromium base) +|Brave |Not tested |Expected compatible (Chromium-based) +|Firefox |Not tested |Requires manifest v3 → v2 conversion +|=== + +''''' + +=== Next Steps (Post-Testing) + +Now that core infrastructure works, proceed with: + +[arabic] +. *Wire YouTube DOM extraction* - Implement +`+YouTubeAdapter.extractSignals()+` fully +. *Connect lens actions* - Wire Random Walk lens to actual tab-opening +behavior +. *Implement feed analysis* - Calculate diversity metrics and display in +popup +. *Test WASM integration* - Call Rust rule engine from content script +. *Profile sharing (v1.5)* - Implement .aep export/import for +perspective-sharing + +''''' + +=== Conclusion + +*🎉 COMPLETE SUCCESS* - All core systems operational: - ✅ Extension +loads and runs - ✅ Service worker active - ✅ Popup UI functional - ✅ +WASM accessible - ✅ Content scripts injecting + +*No blocking issues found.* Ready to proceed with feature +implementation. + +''''' + +*Tested by*: Claude Sonnet 4.5 + User *Sign-off*: Extension ready for +development phase 2 (feature implementation) diff --git a/algorithm-shield/docs/TEST-RESULTS-2026-01-24.md b/algorithm-shield/docs/TEST-RESULTS-2026-01-24.md deleted file mode 100644 index 59f3210..0000000 --- a/algorithm-shield/docs/TEST-RESULTS-2026-01-24.md +++ /dev/null @@ -1,164 +0,0 @@ -# Algorithm Shield - Test Results - -**Date**: 2026-01-24 -**Version**: 0.1.0 -**Browser**: Microsoft Edge Dev (Chromium 140.0.0.0) -**Platform**: Linux (Fedora) - -## Executive Summary - -✅ **ALL CORE TESTS PASSED** - Extension is fully functional and ready for feature implementation. - -## Test Results - -### Test 1: Extension Loading ✅ PASS - -**Action**: Loaded unpacked extension from `~/Documents/hyperpolymath-repos/algorithm-shield/dist/` - -**Issue encountered**: -- Initial manifest had unrecognized keys `_license` and `_copyright` -- Chrome/Edge manifest v3 doesn't support custom fields starting with `_` - -**Fix applied**: -- Removed `_license` and `_copyright` from manifest.json -- Extension loaded successfully after fix - -**Result**: Extension loaded without errors, assigned ID `elpkeefehideemhdinnhdkbiignknacm` - ---- - -### Test 2: Service Worker Activation ✅ PASS - -**Action**: Clicked "service worker" link in extension details - -**Observed**: -- Console showed: `🛡️ Algorithm Shield background worker active` -- Service worker status: **Active** (green indicator) -- No errors in console -- Storage initialization completed successfully - -**Result**: Background script running correctly - ---- - -### Test 3: Popup UI Display ✅ PASS - -**Action**: Clicked extension icon in toolbar - -**Observed**: -- Popup window opened (300x400px as designed) -- HTML/CSS rendered correctly -- All UI elements displayed properly -- Icons showed correctly (shield + membrane design) -- No console errors in popup DevTools - -**Result**: UI fully functional - ---- - -### Test 4: WASM Module Loading ✅ PASS - -**Action**: Checked for WASM loading in Network tab and console - -**Observed**: -- No WASM loading errors appeared in console -- Storage API test passed (state persisting correctly) -- WASM file accessible at `dist/pkg/algorithm_shield_engine_bg.wasm` (181KB) - -**Result**: WASM integration ready (not yet wired to UI, as expected at v0.1) - ---- - -### Test 5: Content Script Injection ✅ PASS - -**Action**: Navigated to YouTube.com and checked console - -**Observed**: -``` -🛡️ Algorithm Shield active -👁️ Observing feed... -``` - -**Also observed** (NOT errors from Algorithm Shield): -- Multiple `ERR_BLOCKED_BY_CLIENT` messages from uBlock Origin ad blocker -- YouTube tracking/analytics requests blocked by ad blocker -- Google DoubleClick ads blocked -- Standard YouTube framework warnings (Polymer, storage permissions) - -**Result**: Content script successfully injected and running on YouTube - ---- - -## Issues Found - -### Issue #1: Manifest Custom Fields ✅ FIXED -- **Severity**: Low (non-blocking warning) -- **Description**: Manifest contained `_license` and `_copyright` fields not recognized by Chrome -- **Fix**: Removed custom fields from both `dist/manifest.json` and source `manifest.json` -- **Status**: Resolved - ---- - -## Known Limitations (Expected at v0.1) - -These are NOT bugs - they're features not yet implemented: - -1. **ReScript code not compiled** - Using JS placeholders currently -2. **WASM not wired to UI** - Module loads but not yet connected to popup/content scripts -3. **Platform adapters stubbed** - YouTube DOM extraction scaffolded but not fully implemented -4. **Lens/Persona logic not connected** - UI buttons present but actions not wired to actual lens implementations -5. **Feed analysis not implemented** - "Observing feed..." message appears but actual analysis pending - -**All expected** - these are the features we're building next! - ---- - -## Performance Metrics - -| Metric | Value | Target | Status | -|--------|-------|--------|--------| -| WASM size | 181 KB | < 500 KB | ✅ Well under target | -| Extension load time | < 1s | < 2s | ✅ Fast | -| Memory usage (idle) | ~15 MB | < 50 MB | ✅ Efficient | -| Content script inject | Immediate | < 500ms | ✅ Fast | - ---- - -## Browser Compatibility - -| Browser | Version | Status | -|---------|---------|--------| -| Edge Dev | 140.0.0.0 | ✅ Fully compatible | -| Chrome | Not tested | Expected compatible (same Chromium base) | -| Brave | Not tested | Expected compatible (Chromium-based) | -| Firefox | Not tested | Requires manifest v3 → v2 conversion | - ---- - -## Next Steps (Post-Testing) - -Now that core infrastructure works, proceed with: - -1. **Wire YouTube DOM extraction** - Implement `YouTubeAdapter.extractSignals()` fully -2. **Connect lens actions** - Wire Random Walk lens to actual tab-opening behavior -3. **Implement feed analysis** - Calculate diversity metrics and display in popup -4. **Test WASM integration** - Call Rust rule engine from content script -5. **Profile sharing (v1.5)** - Implement .aep export/import for perspective-sharing - ---- - -## Conclusion - -**🎉 COMPLETE SUCCESS** - All core systems operational: -- ✅ Extension loads and runs -- ✅ Service worker active -- ✅ Popup UI functional -- ✅ WASM accessible -- ✅ Content scripts injecting - -**No blocking issues found.** Ready to proceed with feature implementation. - ---- - -**Tested by**: Claude Sonnet 4.5 + User -**Sign-off**: Extension ready for development phase 2 (feature implementation) diff --git a/algorithm-shield/docs/TESTING-CHECKLIST.adoc b/algorithm-shield/docs/TESTING-CHECKLIST.adoc new file mode 100644 index 0000000..1f45140 --- /dev/null +++ b/algorithm-shield/docs/TESTING-CHECKLIST.adoc @@ -0,0 +1,263 @@ +== Algorithm Shield - Extension Testing Checklist + +*Date*: 2026-01-24 *Version*: 0.1.0 *Browser*: Edge Dev (Chromium-based) + +=== Pre-Test Setup + +*Extension Location*: +`+~/Documents/hyperpolymath-repos/algorithm-shield/dist/+` + +*Required Files* (verify all present): - ✅ manifest.json - ✅ +background.js - ✅ content.js - ✅ popup.html, popup.css, popup.js - ✅ +assets/icon-16.png, icon-48.png, icon-128.png - ✅ +pkg/algorithm_shield_engine_bg.wasm (181KB) - ✅ +pkg/algorithm_shield_engine.js + +=== Loading the Extension + +==== Step 1: Open Edge Extensions Page + +[arabic] +. Navigate to: `+edge://extensions/+` +. Enable *Developer mode* (toggle in top-right) +. Click *"`Load unpacked`"* +. Select folder: +`+~/Documents/hyperpolymath-repos/algorithm-shield/dist/+` +. Click *"`Select Folder`"* + +*Expected Result*: Extension appears in list with Algorithm Shield icon + +==== Step 2: Verify Extension Loads + +*Check for errors*: - [ ] No red error messages in extension card - [ ] +"`Errors`" button does not appear (or shows 0 errors) - [ ] Extension ID +is assigned - [ ] Version shows "`0.1.0`" + +*If errors appear*: 1. Click "`Errors`" button 2. Copy error messages 3. +Check browser console: `+F12 → Console tab+` + +==== Step 3: Test Service Worker (Background Script) + +[arabic] +. On extensions page, click *"`Service worker`"* link (under extension +details) +. DevTools opens for background script +. Check Console tab for errors + +*Expected Output*: + +.... +Algorithm Shield background service worker initialized +.... + +*Tests*: - [ ] No console errors - [ ] Service worker status: "`Active`" +- [ ] WASM module loads without errors + +*Run in console*: + +[source,javascript] +---- +// Test storage API +chrome.storage.local.set({test: "hello"}, () => { + chrome.storage.local.get("test", (result) => { + console.log("Storage test:", result.test === "hello" ? "✅ PASS" : "❌ FAIL"); + }); +}); + +// Test WASM loading (if exposed globally) +console.log("WASM check:", typeof wasmModule !== 'undefined' ? "✅ Loaded" : "⚠️ Not loaded yet"); +---- + +==== Step 4: Test Popup + +[arabic] +. Click Algorithm Shield icon in toolbar (or pin it first) +. Popup should open + +*Expected Behavior*: - [ ] Popup displays (300x400px window) - [ ] Icon +shows correctly - [ ] HTML/CSS renders properly - [ ] No console errors +in popup DevTools + +*Right-click popup → Inspect* to open DevTools for popup: + +*Tests in popup console*: + +[source,javascript] +---- +// Test chrome.storage from popup +chrome.storage.local.get(null, (data) => { + console.log("All stored data:", data); +}); + +// Test chrome.tabs API +chrome.tabs.query({active: true, currentWindow: true}, (tabs) => { + console.log("Current tab:", tabs[0].url); +}); +---- + +==== Step 5: Test Content Script Injection + +[arabic] +. Navigate to YouTube: https://www.youtube.com/ +. Open DevTools (F12) +. Go to Console tab + +*Expected*: + +.... +Algorithm Shield content script injected on youtube.com +.... + +*Test in console*: + +[source,javascript] +---- +// Check if content script loaded +console.log("Content script:", typeof algorithmShieldContentScript !== 'undefined' ? "✅ Loaded" : "❌ Not loaded"); +---- + +*Look for*: - [ ] Content script logs appear - [ ] No errors about +missing permissions - [ ] Script runs at document_start (before page +loads) + +==== Step 6: Test WASM Integration + +*In background worker console*: + +[source,javascript] +---- +// Try to call WASM functions (example - adjust based on actual exports) +// Check if module loaded +console.log("WASM exports:", Object.keys(wasmExports || {})); +---- + +*Expected*: - [ ] WASM file fetched successfully (check Network tab) - [ +] Size is ~181KB (not 0 bytes) - [ ] MIME type: application/wasm - [ ] +No CORS errors + +==== Step 7: Test Cross-Component Communication + +*In popup console*: + +[source,javascript] +---- +// Send message to background +chrome.runtime.sendMessage({type: "ping"}, (response) => { + console.log("Background response:", response); +}); +---- + +*In background console*: + +[source,javascript] +---- +// Listen for messages +chrome.runtime.onMessage.addListener((message, sender, sendResponse) => { + console.log("Message received:", message); + sendResponse({status: "pong"}); + return true; +}); +---- + +*Tests*: - [ ] Messages send successfully - [ ] Responses received - [ ] +No permission errors + +=== Common Issues & Solutions + +==== Issue: "`Service worker registration failed`" + +*Cause*: Syntax error in background.js or manifest *Fix*: Check console +for exact error, verify manifest.json is valid JSON + +==== Issue: "`Failed to load extension`" + +*Cause*: Missing manifest_version or required fields *Fix*: Verify +manifest.json has all required fields + +==== Issue: WASM file not loading + +*Cause*: Incorrect path or web_accessible_resources misconfigured *Fix*: +Check manifest.json web_accessible_resources matches WASM filename + +==== Issue: Content script not injecting + +*Cause*: host_permissions or matches pattern incorrect *Fix*: Verify +manifest has "`https://__/__`" in host_permissions + +==== Issue: Icons not displaying + +*Cause*: Icon files missing or wrong path *Fix*: Check assets/icon-*.png +exist in dist/ + +==== Issue: "`Cannot read property of undefined`" + +*Cause*: Trying to use uninitialized objects *Fix*: Add null checks, +ensure initialization order + +=== Test Results Log + +*Date*: ___________ *Browser*: Edge Dev v___________ *Extension +Version*: 0.1.0 + +[cols=",,",options="header",] +|=== +|Test |Status |Notes +|Extension loads |⬜ | +|No manifest errors |⬜ | +|Service worker active |⬜ | +|WASM loads (181KB) |⬜ | +|Popup displays |⬜ | +|Storage API works |⬜ | +|Tabs API works |⬜ | +|Content script injects |⬜ | +|Cross-component messaging |⬜ | +|Icons display correctly |⬜ | +|=== + +*Overall Status*: ⬜ PASS / ⬜ FAIL + +*Errors Found*: + +.... +(paste any error messages here) +.... + +*Next Steps*: + +.... +(what needs to be fixed based on test results) +.... + +=== Performance Checks + +==== Memory Usage + +[arabic] +. Open: `+edge://extensions/+` → Click "`Details`" on Algorithm Shield +. Check memory usage (should be < 50MB when idle) + +==== WASM Load Time + +[arabic] +. Check Network tab when extension loads +. WASM should load in < 500ms + +==== Popup Render Time + +[arabic] +. Click icon, check how fast popup appears +. Should be < 200ms + +=== Next Testing Phase + +Once basic loading works, proceed to: - [ ] *Functional testing*: Test +lens implementations - [ ] *Platform integration*: Test YouTube feed +extraction - [ ] *Human timing*: Test bot detection evasion - [ ] *State +persistence*: Test data survives browser restart - [ ] *Error handling*: +Test recovery from failures + +''''' + +*Testing Philosophy*: We test thoroughly because users trust us with +their browsing behavior. Every permission we request, we must use +correctly and safely. diff --git a/algorithm-shield/docs/TESTING-CHECKLIST.md b/algorithm-shield/docs/TESTING-CHECKLIST.md deleted file mode 100644 index 9a96f78..0000000 --- a/algorithm-shield/docs/TESTING-CHECKLIST.md +++ /dev/null @@ -1,244 +0,0 @@ -# Algorithm Shield - Extension Testing Checklist - -**Date**: 2026-01-24 -**Version**: 0.1.0 -**Browser**: Edge Dev (Chromium-based) - -## Pre-Test Setup - -**Extension Location**: `~/Documents/hyperpolymath-repos/algorithm-shield/dist/` - -**Required Files** (verify all present): -- ✅ manifest.json -- ✅ background.js -- ✅ content.js -- ✅ popup.html, popup.css, popup.js -- ✅ assets/icon-16.png, icon-48.png, icon-128.png -- ✅ pkg/algorithm_shield_engine_bg.wasm (181KB) -- ✅ pkg/algorithm_shield_engine.js - -## Loading the Extension - -### Step 1: Open Edge Extensions Page - -1. Navigate to: `edge://extensions/` -2. Enable **Developer mode** (toggle in top-right) -3. Click **"Load unpacked"** -4. Select folder: `~/Documents/hyperpolymath-repos/algorithm-shield/dist/` -5. Click **"Select Folder"** - -**Expected Result**: Extension appears in list with Algorithm Shield icon - -### Step 2: Verify Extension Loads - -**Check for errors**: -- [ ] No red error messages in extension card -- [ ] "Errors" button does not appear (or shows 0 errors) -- [ ] Extension ID is assigned -- [ ] Version shows "0.1.0" - -**If errors appear**: -1. Click "Errors" button -2. Copy error messages -3. Check browser console: `F12 → Console tab` - -### Step 3: Test Service Worker (Background Script) - -1. On extensions page, click **"Service worker"** link (under extension details) -2. DevTools opens for background script -3. Check Console tab for errors - -**Expected Output**: -``` -Algorithm Shield background service worker initialized -``` - -**Tests**: -- [ ] No console errors -- [ ] Service worker status: "Active" -- [ ] WASM module loads without errors - -**Run in console**: -```javascript -// Test storage API -chrome.storage.local.set({test: "hello"}, () => { - chrome.storage.local.get("test", (result) => { - console.log("Storage test:", result.test === "hello" ? "✅ PASS" : "❌ FAIL"); - }); -}); - -// Test WASM loading (if exposed globally) -console.log("WASM check:", typeof wasmModule !== 'undefined' ? "✅ Loaded" : "⚠️ Not loaded yet"); -``` - -### Step 4: Test Popup - -1. Click Algorithm Shield icon in toolbar (or pin it first) -2. Popup should open - -**Expected Behavior**: -- [ ] Popup displays (300x400px window) -- [ ] Icon shows correctly -- [ ] HTML/CSS renders properly -- [ ] No console errors in popup DevTools - -**Right-click popup → Inspect** to open DevTools for popup: - -**Tests in popup console**: -```javascript -// Test chrome.storage from popup -chrome.storage.local.get(null, (data) => { - console.log("All stored data:", data); -}); - -// Test chrome.tabs API -chrome.tabs.query({active: true, currentWindow: true}, (tabs) => { - console.log("Current tab:", tabs[0].url); -}); -``` - -### Step 5: Test Content Script Injection - -1. Navigate to YouTube: https://www.youtube.com/ -2. Open DevTools (F12) -3. Go to Console tab - -**Expected**: -``` -Algorithm Shield content script injected on youtube.com -``` - -**Test in console**: -```javascript -// Check if content script loaded -console.log("Content script:", typeof algorithmShieldContentScript !== 'undefined' ? "✅ Loaded" : "❌ Not loaded"); -``` - -**Look for**: -- [ ] Content script logs appear -- [ ] No errors about missing permissions -- [ ] Script runs at document_start (before page loads) - -### Step 6: Test WASM Integration - -**In background worker console**: -```javascript -// Try to call WASM functions (example - adjust based on actual exports) -// Check if module loaded -console.log("WASM exports:", Object.keys(wasmExports || {})); -``` - -**Expected**: -- [ ] WASM file fetched successfully (check Network tab) -- [ ] Size is ~181KB (not 0 bytes) -- [ ] MIME type: application/wasm -- [ ] No CORS errors - -### Step 7: Test Cross-Component Communication - -**In popup console**: -```javascript -// Send message to background -chrome.runtime.sendMessage({type: "ping"}, (response) => { - console.log("Background response:", response); -}); -``` - -**In background console**: -```javascript -// Listen for messages -chrome.runtime.onMessage.addListener((message, sender, sendResponse) => { - console.log("Message received:", message); - sendResponse({status: "pong"}); - return true; -}); -``` - -**Tests**: -- [ ] Messages send successfully -- [ ] Responses received -- [ ] No permission errors - -## Common Issues & Solutions - -### Issue: "Service worker registration failed" -**Cause**: Syntax error in background.js or manifest -**Fix**: Check console for exact error, verify manifest.json is valid JSON - -### Issue: "Failed to load extension" -**Cause**: Missing manifest_version or required fields -**Fix**: Verify manifest.json has all required fields - -### Issue: WASM file not loading -**Cause**: Incorrect path or web_accessible_resources misconfigured -**Fix**: Check manifest.json web_accessible_resources matches WASM filename - -### Issue: Content script not injecting -**Cause**: host_permissions or matches pattern incorrect -**Fix**: Verify manifest has "https://*/*" in host_permissions - -### Issue: Icons not displaying -**Cause**: Icon files missing or wrong path -**Fix**: Check assets/icon-*.png exist in dist/ - -### Issue: "Cannot read property of undefined" -**Cause**: Trying to use uninitialized objects -**Fix**: Add null checks, ensure initialization order - -## Test Results Log - -**Date**: ___________ -**Browser**: Edge Dev v___________ -**Extension Version**: 0.1.0 - -| Test | Status | Notes | -|------|--------|-------| -| Extension loads | ⬜ | | -| No manifest errors | ⬜ | | -| Service worker active | ⬜ | | -| WASM loads (181KB) | ⬜ | | -| Popup displays | ⬜ | | -| Storage API works | ⬜ | | -| Tabs API works | ⬜ | | -| Content script injects | ⬜ | | -| Cross-component messaging | ⬜ | | -| Icons display correctly | ⬜ | | - -**Overall Status**: ⬜ PASS / ⬜ FAIL - -**Errors Found**: -``` -(paste any error messages here) -``` - -**Next Steps**: -``` -(what needs to be fixed based on test results) -``` - -## Performance Checks - -### Memory Usage -1. Open: `edge://extensions/` → Click "Details" on Algorithm Shield -2. Check memory usage (should be < 50MB when idle) - -### WASM Load Time -1. Check Network tab when extension loads -2. WASM should load in < 500ms - -### Popup Render Time -1. Click icon, check how fast popup appears -2. Should be < 200ms - -## Next Testing Phase - -Once basic loading works, proceed to: -- [ ] **Functional testing**: Test lens implementations -- [ ] **Platform integration**: Test YouTube feed extraction -- [ ] **Human timing**: Test bot detection evasion -- [ ] **State persistence**: Test data survives browser restart -- [ ] **Error handling**: Test recovery from failures - ---- - -**Testing Philosophy**: We test thoroughly because users trust us with their browsing behavior. Every permission we request, we must use correctly and safely. diff --git a/disinfo-nesy-detector/ABI-FFI-README.md b/defensive-multiplicity/ABI-FFI-README.adoc similarity index 74% rename from disinfo-nesy-detector/ABI-FFI-README.md rename to defensive-multiplicity/ABI-FFI-README.adoc index f06f72c..f1163e3 100644 --- a/disinfo-nesy-detector/ABI-FFI-README.md +++ b/defensive-multiplicity/ABI-FFI-README.adoc @@ -1,19 +1,22 @@ -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -45,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -77,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -97,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -111,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -125,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -140,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -215,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -237,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -259,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -282,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -312,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -342,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/defensive-multiplicity/CODE_OF_CONDUCT.adoc b/defensive-multiplicity/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/defensive-multiplicity/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/defensive-multiplicity/CODE_OF_CONDUCT.md b/defensive-multiplicity/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/defensive-multiplicity/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/defensive-multiplicity/CONTRIBUTING.adoc b/defensive-multiplicity/CONTRIBUTING.adoc index eb045d6..e48f66c 100644 --- a/defensive-multiplicity/CONTRIBUTING.adoc +++ b/defensive-multiplicity/CONTRIBUTING.adoc @@ -1,20 +1,111 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Contributing Guide +== Clone the repository -== Getting Started +git clone +https://github.com/hyperpolymath/misinformation-defence-platform.git cd +misinformation-defence-platform -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request +== Using Nix (recommended for reproducibility) -== Commit Guidelines +nix develop -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits +== Or using toolbox/distrobox -== License +toolbox create misinformation-defence-platform-dev toolbox enter +misinformation-defence-platform-dev # Install dependencies manually -Contributions licensed under project license. +== Verify setup +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +misinformation-defence-platform/ ├── src/ # Source code (Perimeter 1-2) +├── lib/ # Library code (Perimeter 1-2) ├── extensions/ # Extensions +(Perimeter 2) ├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling +(Perimeter 2) ├── docs/ # Documentation (Perimeter 3) │ ├── +architecture/ # ADRs, specs (Perimeter 2) │ └── proposals/ # RFCs +(Perimeter 3) ├── examples/ # Examples (Perimeter 3) ├── spec/ # Spec +tests (Perimeter 3) ├── tests/ # Test suite (Perimeter 2-3) ├── +.well-known/ # Protocol files (Perimeter 1-3) ├── .github/ # GitHub +config (Perimeter 1) │ ├── ISSUE_TEMPLATE/ │ └── workflows/ ├── +CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md # This file ├── +GOVERNANCE.md ├── LICENSE ├── MAINTAINERS.md ├── README.adoc ├── +SECURITY.md ├── flake.nix # Nix flake (Perimeter 1) └── Justfile # Task +runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/defensive-multiplicity/CONTRIBUTING.md b/defensive-multiplicity/CONTRIBUTING.md deleted file mode 100644 index 7e4af22..0000000 --- a/defensive-multiplicity/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/misinformation-defence-platform.git -cd misinformation-defence-platform - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create misinformation-defence-platform-dev -toolbox enter misinformation-defence-platform-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -misinformation-defence-platform/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/defensive-multiplicity/ETHICS_CHARTER.adoc b/defensive-multiplicity/ETHICS_CHARTER.adoc new file mode 100644 index 0000000..5489f09 --- /dev/null +++ b/defensive-multiplicity/ETHICS_CHARTER.adoc @@ -0,0 +1,97 @@ +== Ethics Charter for Defensive Multiplicity + +=== Preamble + +This charter establishes the ethical boundaries for implementing +Defensive Multiplicity systems. Inspired by Wittgenstein’s +language-games framework, we recognize that synthetic identities must +operate within agreed-upon rules to maintain societal trust. + +=== Core Principles + +==== Purpose-Bound Identities + +____ +"`No persona shall be used beyond its declared purpose`" +____ + +* All synthetic elements must contain cryptographic truth claims +* Personas shall not engage in activities their human operators would +not + +==== Transparent Obfuscation + +____ +"`All synthetic elements must contain cryptographic truth claims`" +____ + +* Watermarking standards for synthetic content +* Clear disclosure protocols for interactions + +==== Non-Interference Principle + +____ +"`No persona shall diminish another’s capacity for truth-telling`" +____ + +* Synthetic identities must not suppress authentic voices +* Personas shall not engage in harassment or manipulation + +==== Epistemic Accountability + +____ +"`All outputs must be verifiably anchored to accountable human authors`" +____ + +* Cryptographic proof-of-humanity systems +* Audit trails for all persona activities + +=== Implementation Guidelines + +==== Identity Management + +* Maximum persona lifespan: 180 days without renewal +* Mandatory behavioral consistency audits +* Geographic constraints: personas cannot be in two places +simultaneously + +==== Interaction Protocols + +* Clear demarcation between synthetic and authentic communications +* No romantic or financial engagements by synthetic personas +* Mandatory disclosure when synthetic identities engage in public +discourse + +==== Governance Requirements + +* Independent oversight boards with multi-stakeholder representation +* Regular ethical audits of persona networks +* Public transparency reports on system usage + +=== Enforcement Mechanisms + +==== Technical Safeguards + +* Automatic persona deactivation upon ethical breach +* Behavioral anomaly detection systems +* Cryptographic identity chaining + +==== Community Accountability + +* Peer review systems for persona networks +* Reputation systems for human operators +* Whistleblower protections for ethical violations + +==== Legal Compliance + +* Jurisdiction-specific implementation guidelines +* Right-to-be-forgotten protocols +* Data protection impact assessments + +=== Conclusion + +This ethical framework transforms Defensive Multiplicity from a +technical capability into a socially responsible practice. By adhering +to these principles, synthetic identities serve truth rather than +obscuring it, protect rather than deceive, and empower rather than +manipulate. diff --git a/defensive-multiplicity/ETHICS_CHARTER.md b/defensive-multiplicity/ETHICS_CHARTER.md deleted file mode 100644 index bc4cce0..0000000 --- a/defensive-multiplicity/ETHICS_CHARTER.md +++ /dev/null @@ -1,79 +0,0 @@ -# Ethics Charter for Defensive Multiplicity - -## Preamble - -This charter establishes the ethical boundaries for implementing Defensive Multiplicity systems. Inspired by Wittgenstein's language-games framework, we recognize that synthetic identities must operate within agreed-upon rules to maintain societal trust. - -## Core Principles - -### Purpose-Bound Identities - -> "No persona shall be used beyond its declared purpose" - -- All synthetic elements must contain cryptographic truth claims -- Personas shall not engage in activities their human operators would not - -### Transparent Obfuscation - -> "All synthetic elements must contain cryptographic truth claims" - -- Watermarking standards for synthetic content -- Clear disclosure protocols for interactions - -### Non-Interference Principle - -> "No persona shall diminish another's capacity for truth-telling" - -- Synthetic identities must not suppress authentic voices -- Personas shall not engage in harassment or manipulation - -### Epistemic Accountability - -> "All outputs must be verifiably anchored to accountable human authors" - -- Cryptographic proof-of-humanity systems -- Audit trails for all persona activities - -## Implementation Guidelines - -### Identity Management - -- Maximum persona lifespan: 180 days without renewal -- Mandatory behavioral consistency audits -- Geographic constraints: personas cannot be in two places simultaneously - -### Interaction Protocols - -- Clear demarcation between synthetic and authentic communications -- No romantic or financial engagements by synthetic personas -- Mandatory disclosure when synthetic identities engage in public discourse - -### Governance Requirements - -- Independent oversight boards with multi-stakeholder representation -- Regular ethical audits of persona networks -- Public transparency reports on system usage - -## Enforcement Mechanisms - -### Technical Safeguards - -- Automatic persona deactivation upon ethical breach -- Behavioral anomaly detection systems -- Cryptographic identity chaining - -### Community Accountability - -- Peer review systems for persona networks -- Reputation systems for human operators -- Whistleblower protections for ethical violations - -### Legal Compliance - -- Jurisdiction-specific implementation guidelines -- Right-to-be-forgotten protocols -- Data protection impact assessments - -## Conclusion - -This ethical framework transforms Defensive Multiplicity from a technical capability into a socially responsible practice. By adhering to these principles, synthetic identities serve truth rather than obscuring it, protect rather than deceive, and empower rather than manipulate. diff --git a/defensive-multiplicity/README.adoc b/defensive-multiplicity/README.adoc index 614df2e..7cd5b6e 100644 --- a/defensive-multiplicity/README.adoc +++ b/defensive-multiplicity/README.adoc @@ -1,101 +1,54 @@ -= RSR template repo - see RSR_OUTLINE.adoc in root for general background and specification +image:https://img.shields.io/badge/License-MPL–2.0-blue.svg[License: +PMPL-1.0,link="`https://github.com/hyperpolymath/palimpsest-license`"] -== This is your repo - don't forget to rename me! +== Defensive Multiplicity Framework -== ABI/FFI Standards (Hyperpolymath Universal Standard) +image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="`https://github.com/hyperpolymath/palimpsest-license`"] -**All repos with foreign function interfaces MUST follow this standard:** +=== Overview -* **ABI (Application Binary Interface)** → **Idris2** (`src/abi/*.idr`) -** Type definitions with dependent type proofs -** Memory layout verification -** Platform-specific ABIs with compile-time selection -** Formal verification of interface correctness +This repository contains the theoretical framework, implementation +guidelines, and governance structures for Defensive Multiplicity - a +paradigm shift in digital privacy that achieves security through +controlled identity proliferation rather than concealment. -* **FFI (Foreign Function Interface)** → **Zig** (`ffi/zig/src/*.zig`) -** C-compatible function implementations -** Zero-cost abstractions -** Memory-safe by default -** Cross-compilation support +=== Structure -* **Generated C Headers** → Auto-generated from Idris2 ABI (`generated/abi/*.h`) -** Bridge between Idris2 and Zig -** Consumed by any language via C ABI +DefensiveMultiplicity-Framework/ ├── docs/ # Theoretical foundations ├── +implementations/ # Practical toolkits ├── research/ # Threat analysis +├── governance/ # Ethical oversight └── tech/ # Core systems -**Directory Structure:** ----- -project/ -├── src/abi/ # Idris2 ABI definitions (REQUIRED) -├── ffi/zig/ # Zig FFI implementation (REQUIRED) -├── generated/abi/ # Auto-generated C headers -└── bindings/ # Language-specific wrappers (optional) ----- +=== Key Components -**See:** `ABI-FFI-README.md` for complete documentation +[arabic] +. *Whitepaper*: Theoretical foundation in `+docs/WHITEPAPER.md+` +. *Ethics Charter*: Wittgensteinian rules of engagement in +`+docs/ETHICS_CHARTER.md+` +. *Implementation Kits*: Ready-to-use systems in `+implementations/+` +. *Governance Framework*: Oversight protocols in `+governance/+` -== AI CLI standards +=== Getting Started -- Include `ai-cli-crash-capture/` and `contractiles/` from this template in new repos. -- Mirror 6SCM files into `.machine_readable/` (NOT `.machine_readable/6scm/`). -- Before any code generation, check `/var$REPOS_DIR/proven` for the current Idris "unbreakable" library status. -- If a project uses that Idris library, add an *Idris Inside* badge to the repo. -- If new bindings are required, add them in `/var$REPOS_DIR/proven` as `idris2-zig-` during the work. -- If new code suggests additional "unbreakable" Idris modules, add them under `/var$REPOS_DIR/proven` and update binders across all supported languages. +[arabic] +. Review the whitepaper and ethics charter +. Select the appropriate implementation kit for your use case +. Follow the governance protocols for ethical deployment -== Standard Dependencies +=== License -=== Web Projects +This work is licensed under the Palimpsest License - a custom license +designed for ethical defensive technologies that: - Permits use for +protective purposes - Prohibits weaponization - Requires ethical +compliance - Mandates transparency about synthetic elements -ReScript web projects in the hyperpolymath ecosystem **MUST** use these formally verified components: +=== Contributing -[cols="1,2,1"] -|=== -|Library |Purpose |Status +Contributions are welcome but must: 1. Align with the ethical charter 2. +Pass governance review 3. Include transparency documentation -|link:https://github.com/hyperpolymath/rescript-dom-mounter[rescript-dom-mounter] -|Formally verified DOM mounting -|**REQUIRED** +=== Warning -|link:https://github.com/hyperpolymath/rescript-tea[rescript-tea] -|TEA architecture framework -|Recommended - -|link:https://github.com/hyperpolymath/cadre-tea-router[cadre-tea-router] -|Proven-safe URL routing -|Recommended - -|link:https://github.com/hyperpolymath/proven[proven] -|Idris2 formally verified library -|Core Dependency -|=== - -==== Why SafeDOM is Required - -Traditional DOM mounting can fail: - -[source,javascript] ----- -// ❌ UNSAFE: Can crash with null pointer -const el = document.getElementById('app') -el.innerHTML = html // 💥 ----- - -SafeDOM provides **compile-time proofs** that DOM operations cannot fail: - -[source,rescript] ----- -// ✅ PROVEN SAFE: Mathematically guaranteed -SafeDOM.mountSafe("#app", html, - ~onSuccess=el => Console.log("Success"), - ~onError=err => Console.error(err)) ----- - -**Mathematical Guarantees:** - -✓ No null pointer dereferences (Idris2 proof) -✓ No invalid CSS selectors (dependent types) -✓ No malformed HTML (balanced tag checking) -✓ Type-safe operations (ReScript + Idris2) -✓ Zero runtime overhead (proofs erased) - -See link:https://github.com/hyperpolymath/rescript-dom-mounter[rescript-dom-mounter documentation] for full details. +This repository contains dual-use technology. By accessing these +materials, you agree to: 1. Never use these tools for harassment or +fraud 2. Disclose any vulnerabilities responsibly 3. Accept that +defensive systems may be weaponized diff --git a/defensive-multiplicity/README.md b/defensive-multiplicity/README.md deleted file mode 100644 index 4f6f23b..0000000 --- a/defensive-multiplicity/README.md +++ /dev/null @@ -1,57 +0,0 @@ -image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] - -# Defensive Multiplicity Framework - - - - -image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"] - - -## Overview - -This repository contains the theoretical framework, implementation guidelines, and governance structures for Defensive Multiplicity - a paradigm shift in digital privacy that achieves security through controlled identity proliferation rather than concealment. - -## Structure - -DefensiveMultiplicity-Framework/ -├── docs/ # Theoretical foundations -├── implementations/ # Practical toolkits -├── research/ # Threat analysis -├── governance/ # Ethical oversight -└── tech/ # Core systems - -## Key Components - -1. **Whitepaper**: Theoretical foundation in `docs/WHITEPAPER.md` -2. **Ethics Charter**: Wittgensteinian rules of engagement in `docs/ETHICS_CHARTER.md` -3. **Implementation Kits**: Ready-to-use systems in `implementations/` -4. **Governance Framework**: Oversight protocols in `governance/` - -## Getting Started - -1. Review the whitepaper and ethics charter -2. Select the appropriate implementation kit for your use case -3. Follow the governance protocols for ethical deployment - -## License - -This work is licensed under the Palimpsest License - a custom license designed for ethical defensive technologies that: -- Permits use for protective purposes -- Prohibits weaponization -- Requires ethical compliance -- Mandates transparency about synthetic elements - -## Contributing - -Contributions are welcome but must: -1. Align with the ethical charter -2. Pass governance review -3. Include transparency documentation - -## Warning - -This repository contains dual-use technology. By accessing these materials, you agree to: -1. Never use these tools for harassment or fraud -2. Disclose any vulnerabilities responsibly -3. Accept that defensive systems may be weaponized diff --git a/defensive-multiplicity/SECURITY.adoc b/defensive-multiplicity/SECURITY.adoc new file mode 100644 index 0000000..fdcacf9 --- /dev/null +++ b/defensive-multiplicity/SECURITY.adoc @@ -0,0 +1,81 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |:white_check_mark: +|=== + +=== Reporting a Vulnerability + +We take security seriously in the Defensive Multiplicity framework. If +you discover a security vulnerability, please follow our responsible +disclosure process. + +==== How to Report + +[arabic] +. *Do NOT* create a public GitHub issue for security vulnerabilities +. Email security concerns to: `+security@hyperpolymath.org+` +. Include: +* Description of the vulnerability +* Steps to reproduce +* Potential impact assessment +* Suggested remediation (if any) + +==== Response Timeline + +* *Initial Response*: Within 48 hours +* *Triage Complete*: Within 7 days +* *Resolution Target*: Within 30 days (severity dependent) + +==== Scope + +This security policy covers: + +* Vulnerabilities in the ethical framework specifications +* Flaws in cryptographic identity protocols (when implemented) +* Issues with persona lifecycle management (when implemented) +* Weaknesses in audit trail mechanisms (when implemented) + +==== Out of Scope + +* Theoretical attacks without practical demonstration +* Social engineering attacks on project maintainers +* Issues in third-party dependencies (report to upstream) + +=== Security Considerations for Implementations + +When implementing the Defensive Multiplicity framework, consider: + +==== Identity Management + +* Use cryptographically secure random number generators for persona IDs +* Implement proper key management for identity chaining +* Ensure persona deactivation cannot be bypassed + +==== Audit Trails + +* Use append-only logs with cryptographic integrity +* Implement tamper-evident logging +* Protect audit data at rest and in transit + +==== Disclosure Protocols + +* Verify watermark authenticity before trust decisions +* Implement rate limiting on verification endpoints +* Protect against timing attacks in verification + +=== Acknowledgments + +We maintain a list of security researchers who have responsibly +disclosed vulnerabilities: + +_No disclosures yet - be the first!_ + +=== Contact + +* Security Team: `+security@hyperpolymath.org+` +* Maintainer: `+j.d.a.jewell@open.ac.uk+` diff --git a/defensive-multiplicity/SECURITY.md b/defensive-multiplicity/SECURITY.md deleted file mode 100644 index 8b2495e..0000000 --- a/defensive-multiplicity/SECURITY.md +++ /dev/null @@ -1,72 +0,0 @@ -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 0.1.x | :white_check_mark: | - -## Reporting a Vulnerability - -We take security seriously in the Defensive Multiplicity framework. If you discover a security vulnerability, please follow our responsible disclosure process. - -### How to Report - -1. **Do NOT** create a public GitHub issue for security vulnerabilities -2. Email security concerns to: `security@hyperpolymath.org` -3. Include: - - Description of the vulnerability - - Steps to reproduce - - Potential impact assessment - - Suggested remediation (if any) - -### Response Timeline - -- **Initial Response**: Within 48 hours -- **Triage Complete**: Within 7 days -- **Resolution Target**: Within 30 days (severity dependent) - -### Scope - -This security policy covers: - -- Vulnerabilities in the ethical framework specifications -- Flaws in cryptographic identity protocols (when implemented) -- Issues with persona lifecycle management (when implemented) -- Weaknesses in audit trail mechanisms (when implemented) - -### Out of Scope - -- Theoretical attacks without practical demonstration -- Social engineering attacks on project maintainers -- Issues in third-party dependencies (report to upstream) - -## Security Considerations for Implementations - -When implementing the Defensive Multiplicity framework, consider: - -### Identity Management -- Use cryptographically secure random number generators for persona IDs -- Implement proper key management for identity chaining -- Ensure persona deactivation cannot be bypassed - -### Audit Trails -- Use append-only logs with cryptographic integrity -- Implement tamper-evident logging -- Protect audit data at rest and in transit - -### Disclosure Protocols -- Verify watermark authenticity before trust decisions -- Implement rate limiting on verification endpoints -- Protect against timing attacks in verification - -## Acknowledgments - -We maintain a list of security researchers who have responsibly disclosed vulnerabilities: - -*No disclosures yet - be the first!* - -## Contact - -- Security Team: `security@hyperpolymath.org` -- Maintainer: `j.d.a.jewell@open.ac.uk` diff --git a/algorithm-shield/ABI-FFI-README.md b/disinfo-nesy-detector/ABI-FFI-README.adoc similarity index 74% rename from algorithm-shield/ABI-FFI-README.md rename to disinfo-nesy-detector/ABI-FFI-README.adoc index f06f72c..f1163e3 100644 --- a/algorithm-shield/ABI-FFI-README.md +++ b/disinfo-nesy-detector/ABI-FFI-README.adoc @@ -1,19 +1,22 @@ -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -45,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -77,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -97,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -111,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -125,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -140,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -215,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -237,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -259,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -282,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -312,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -342,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/disinfo-nesy-detector/CODE_OF_CONDUCT.adoc b/disinfo-nesy-detector/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/disinfo-nesy-detector/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/disinfo-nesy-detector/CODE_OF_CONDUCT.md b/disinfo-nesy-detector/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/disinfo-nesy-detector/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/disinfo-nesy-detector/CONTRIBUTING.adoc b/disinfo-nesy-detector/CONTRIBUTING.adoc index eb045d6..e48f66c 100644 --- a/disinfo-nesy-detector/CONTRIBUTING.adoc +++ b/disinfo-nesy-detector/CONTRIBUTING.adoc @@ -1,20 +1,111 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Contributing Guide +== Clone the repository -== Getting Started +git clone +https://github.com/hyperpolymath/misinformation-defence-platform.git cd +misinformation-defence-platform -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request +== Using Nix (recommended for reproducibility) -== Commit Guidelines +nix develop -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits +== Or using toolbox/distrobox -== License +toolbox create misinformation-defence-platform-dev toolbox enter +misinformation-defence-platform-dev # Install dependencies manually -Contributions licensed under project license. +== Verify setup +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +misinformation-defence-platform/ ├── src/ # Source code (Perimeter 1-2) +├── lib/ # Library code (Perimeter 1-2) ├── extensions/ # Extensions +(Perimeter 2) ├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling +(Perimeter 2) ├── docs/ # Documentation (Perimeter 3) │ ├── +architecture/ # ADRs, specs (Perimeter 2) │ └── proposals/ # RFCs +(Perimeter 3) ├── examples/ # Examples (Perimeter 3) ├── spec/ # Spec +tests (Perimeter 3) ├── tests/ # Test suite (Perimeter 2-3) ├── +.well-known/ # Protocol files (Perimeter 1-3) ├── .github/ # GitHub +config (Perimeter 1) │ ├── ISSUE_TEMPLATE/ │ └── workflows/ ├── +CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md # This file ├── +GOVERNANCE.md ├── LICENSE ├── MAINTAINERS.md ├── README.adoc ├── +SECURITY.md ├── flake.nix # Nix flake (Perimeter 1) └── Justfile # Task +runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/disinfo-nesy-detector/CONTRIBUTING.md b/disinfo-nesy-detector/CONTRIBUTING.md deleted file mode 100644 index 7e4af22..0000000 --- a/disinfo-nesy-detector/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/misinformation-defence-platform.git -cd misinformation-defence-platform - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create misinformation-defence-platform-dev -toolbox enter misinformation-defence-platform-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -misinformation-defence-platform/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/misinformation-defence-platform/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/disinfo-nesy-detector/RUST_CONVERSION_NEEDED.adoc b/disinfo-nesy-detector/RUST_CONVERSION_NEEDED.adoc new file mode 100644 index 0000000..3b1146f --- /dev/null +++ b/disinfo-nesy-detector/RUST_CONVERSION_NEEDED.adoc @@ -0,0 +1,38 @@ +== Go → Rust Conversion Required + +This repository needs conversion from Go to Rust per RSR policy. + +=== Current Components + +* *NATS JetStream*: Message streaming → Use `+async-nats+` crate +* *ONNX Runtime*: ML inference → Use `+ort+` crate +* *Souffle Wrapper*: Datalog → Use `+crepe+` or FFI to Souffle +* *Prometheus*: Metrics → Use `+prometheus+` crate +* *Protobuf*: Serialization → Use `+prost+` crate + +=== Rust Equivalent Crates + +[source,toml] +---- +[dependencies] +async-nats = "0.33" +ort = "2.0" +prometheus = "0.13" +prost = "0.12" +tokio = { version = "1", features = ["full"] } +tracing = "0.1" +---- + +=== Conversion Steps + +[arabic] +. Create Cargo.toml with above dependencies +. Convert pkg/onnx_wrapper → Rust ONNX bindings +. Convert pkg/souffle_wrapper → Rust Datalog (crepe or FFI) +. Convert cmd/main.go → Rust async main with tokio +. Generate Rust protobuf from .proto files +. Test with NATS and ONNX model + +=== Priority + +High - ML inference service needs Rust’s safety guarantees. diff --git a/disinfo-nesy-detector/RUST_CONVERSION_NEEDED.md b/disinfo-nesy-detector/RUST_CONVERSION_NEEDED.md deleted file mode 100644 index 9544783..0000000 --- a/disinfo-nesy-detector/RUST_CONVERSION_NEEDED.md +++ /dev/null @@ -1,32 +0,0 @@ -# Go → Rust Conversion Required - -This repository needs conversion from Go to Rust per RSR policy. - -## Current Components -- **NATS JetStream**: Message streaming → Use `async-nats` crate -- **ONNX Runtime**: ML inference → Use `ort` crate -- **Souffle Wrapper**: Datalog → Use `crepe` or FFI to Souffle -- **Prometheus**: Metrics → Use `prometheus` crate -- **Protobuf**: Serialization → Use `prost` crate - -## Rust Equivalent Crates -```toml -[dependencies] -async-nats = "0.33" -ort = "2.0" -prometheus = "0.13" -prost = "0.12" -tokio = { version = "1", features = ["full"] } -tracing = "0.1" -``` - -## Conversion Steps -1. Create Cargo.toml with above dependencies -2. Convert pkg/onnx_wrapper → Rust ONNX bindings -3. Convert pkg/souffle_wrapper → Rust Datalog (crepe or FFI) -4. Convert cmd/main.go → Rust async main with tokio -5. Generate Rust protobuf from .proto files -6. Test with NATS and ONNX model - -## Priority -High - ML inference service needs Rust's safety guarantees. diff --git a/disinfo-nesy-detector/SECURITY.adoc b/disinfo-nesy-detector/SECURITY.adoc new file mode 100644 index 0000000..b0574df --- /dev/null +++ b/disinfo-nesy-detector/SECURITY.adoc @@ -0,0 +1,24 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|main |:white_check_mark: +|< main |:x: +|=== + +=== Reporting a Vulnerability + +Please report security vulnerabilities through GitHub private +vulnerability reporting: 1. Go to the *Security* tab 2. Click *Report a +vulnerability* 3. Fill out the form + +We respond within 48 hours. + +=== Security Measures + +* Dependabot for dependency updates +* CodeQL for code scanning +* Secret scanning and push protection diff --git a/disinfo-nesy-detector/SECURITY.md b/disinfo-nesy-detector/SECURITY.md deleted file mode 100644 index 159a0b7..0000000 --- a/disinfo-nesy-detector/SECURITY.md +++ /dev/null @@ -1,25 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| main | :white_check_mark: | -| < main | :x: | - -## Reporting a Vulnerability - -Please report security vulnerabilities through GitHub private vulnerability reporting: -1. Go to the **Security** tab -2. Click **Report a vulnerability** -3. Fill out the form - -We respond within 48 hours. - -## Security Measures - -- Dependabot for dependency updates -- CodeQL for code scanning -- Secret scanning and push protection - diff --git a/disinfo-nesy-detector/docs/architecture/README.adoc b/disinfo-nesy-detector/docs/architecture/README.adoc new file mode 100644 index 0000000..1ff97f9 --- /dev/null +++ b/disinfo-nesy-detector/docs/architecture/README.adoc @@ -0,0 +1,19 @@ +== NSAI Disinfo Detector Architecture + +=== Components + +* *Go Orchestrator*: NATS JetStream consumer, ONNX/Souffle pipeline. +* *Dgraph*: Knowledge graph for symbolic facts. +* *NATSS*: Message broker for scalability. +* *Podman*: Container runtime (immutable, rootless). +* *SaltStack*: Configuration management and rollback. + +=== Diagrams + +* link:diagrams/system.excalidraw[System Architecture] +* link:diagrams/data_flow.mermaid[Data Flow] + +=== Policies + +* link:policies/security.md[Security Policy] +* link:policies/rollback.md[Rollback Procedure] diff --git a/disinfo-nesy-detector/docs/architecture/README.md b/disinfo-nesy-detector/docs/architecture/README.md deleted file mode 100644 index 9a9fe59..0000000 --- a/disinfo-nesy-detector/docs/architecture/README.md +++ /dev/null @@ -1,16 +0,0 @@ -# NSAI Disinfo Detector Architecture - -## Components -- **Go Orchestrator**: NATS JetStream consumer, ONNX/Souffle pipeline. -- **Dgraph**: Knowledge graph for symbolic facts. -- **NATSS**: Message broker for scalability. -- **Podman**: Container runtime (immutable, rootless). -- **SaltStack**: Configuration management and rollback. - -## Diagrams -- [System Architecture](diagrams/system.excalidraw) -- [Data Flow](diagrams/data_flow.mermaid) - -## Policies -- [Security Policy](policies/security.md) -- [Rollback Procedure](policies/rollback.md) diff --git a/docs/reports/audit/audit-2026-04-15-pre.adoc b/docs/reports/audit/audit-2026-04-15-pre.adoc new file mode 100644 index 0000000..6de6b93 --- /dev/null +++ b/docs/reports/audit/audit-2026-04-15-pre.adoc @@ -0,0 +1,15 @@ +== Audit Pre-Report (2026-04-15) + +=== Repository: misinformation-defence-platform + +==== Current State + +* *Branch:* main (behind origin/main by 2 commits) +* *Pending Changes:* +** algorithm-shield/.tool-versions (staged) +** Justfile (modified, added import? "`contractile.just`") +* *SCM Files Found:* +** ./guix.scm +* *Dependabot PRs:* None +* *Workflows:* Checking… +* *Lockfiles:* Checking… diff --git a/docs/reports/audit/audit-2026-04-15-pre.md b/docs/reports/audit/audit-2026-04-15-pre.md deleted file mode 100644 index ae28f68..0000000 --- a/docs/reports/audit/audit-2026-04-15-pre.md +++ /dev/null @@ -1,13 +0,0 @@ -# Audit Pre-Report (2026-04-15) -## Repository: misinformation-defence-platform - -### Current State -- **Branch:** main (behind origin/main by 2 commits) -- **Pending Changes:** - - algorithm-shield/.tool-versions (staged) - - Justfile (modified, added import? "contractile.just") -- **SCM Files Found:** - - ./guix.scm -- **Dependabot PRs:** None -- **Workflows:** Checking... -- **Lockfiles:** Checking... diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..d76dbab --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — misinformation-defence-platform — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |93 +|`+docs/+` files |5 +|`+docs/+` LoC |1266 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +93 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 186c64e..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — misinformation-defence-platform — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 93 | -| `docs/` files | 5 | -| `docs/` LoC | 1266 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 93 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..6d01bb6 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — misinformation-defence-platform (Developer) + +=== What is misinformation-defence-platform? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 775ef4f..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — misinformation-defence-platform (Developer) - -## What is misinformation-defence-platform? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..e87cb1b --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — misinformation-defence-platform (User) + +=== What is misinformation-defence-platform? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 2f633f8..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — misinformation-defence-platform (User) - -## What is misinformation-defence-platform? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture