From 906eeac735c6a61b8783e9431e92d4cd4f5dc8b8 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 23 Aug 2026 20:00:46 +0100 Subject: [PATCH 1/2] chore: global textual eradication of Nix and ReScript --- .github/dependabot.yml | 4 ++-- ABI-FFI-README.md | 4 ++-- CONTRIBUTING.md | 6 +++--- RSR_OUTLINE.adoc | 8 ++++---- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 4d9ae2f..07f9937 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -44,8 +44,8 @@ updates: schedule: interval: "weekly" - # Nix flakes - - package-ecosystem: "nix" + # Guix flakes + - package-ecosystem: "guix" directory: "/" schedule: interval: "weekly" diff --git a/ABI-FFI-README.md b/ABI-FFI-README.md index 0599561..1606d48 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.md @@ -47,7 +47,7 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ▼ ┌─────────────────────────────────────────────┐ │ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ +│ - Rust, AffineScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ ``` @@ -79,7 +79,7 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ └── bindings/ # Language-specific wrappers (optional) ├── rust/ - ├── rescript/ + ├── affinescript/ └── julia/ ``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 769d49f..d6b8ee4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,8 +6,8 @@ Copyright (c) Jonathan D.A. Jewell git clone https://github.com/hyperpolymath/Axiology.jl.git cd Axiology.jl -# Using Nix (recommended for reproducibility) -nix develop +# Using Guix (recommended for reproducibility) +guix develop # Or using toolbox/distrobox toolbox create Axiology.jl-dev @@ -45,7 +45,7 @@ Axiology.jl/ ├── MAINTAINERS.md ├── README.adoc ├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) +├── flake.guix # Guix flake (Perimeter 1) └── Justfile # Task runner (Perimeter 1) ``` diff --git a/RSR_OUTLINE.adoc b/RSR_OUTLINE.adoc index 4acbfed..6b0158d 100644 --- a/RSR_OUTLINE.adoc +++ b/RSR_OUTLINE.adoc @@ -148,8 +148,8 @@ project/ === Language Tiers -* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, ReScript -* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Nix +* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, AffineScript +* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Guix * **Infrastructure**: Guix channels, derivations === Required Files @@ -163,12 +163,12 @@ project/ * `.well-known/security.txt` * `.well-known/ai.txt` * `.well-known/humans.txt` -* `guix.scm` OR `flake.nix` +* `guix.scm` OR `flake.guix` === Prohibited * Python outside `salt/` directory -* TypeScript/JavaScript (use ReScript) +* TypeScript/JavaScript (use AffineScript) * CUE (use Guile/Nickel) * `Dockerfile` (use `Containerfile`) From 059b01151f4f732e69acf1e969b013082f790898 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 07:43:53 +0100 Subject: [PATCH 2/2] refactor: migrate repository documentation from Markdown to AsciiDoc --- ABI-FFI-README.md => ABI-FFI-README.adoc | 244 +++++----- CODE_OF_CONDUCT.adoc | 339 +++++++++++++ CODE_OF_CONDUCT.md | 331 ------------- CONTRIBUTING.adoc | 109 +++++ CONTRIBUTING.md | 120 ----- GOVERNANCE.adoc | 178 ++----- GOVERNANCE.md | 60 --- PROOF-NEEDS.adoc | 13 + PROOF-NEEDS.md | 14 - README.adoc | 326 +++++++++++++ README.md | 361 -------------- REQUIRES_INITIALISATION.adoc | 92 ++++ REQUIRES_INITIALISATION.md | 86 ---- SECURITY.adoc | 452 +++++++++++++++++ SECURITY.md | 410 ---------------- TEST-NEEDS.adoc | 32 ++ TEST-NEEDS.md | 33 -- TOPOLOGY.md => TOPOLOGY.adoc | 42 +- docs/theory/AXIOLOGY_FOUNDATIONS.adoc | 320 ++++++++++++ docs/theory/AXIOLOGY_FOUNDATIONS.md | 316 ------------ docs/theory/CROSS_CULTURAL_PERSPECTIVES.adoc | 435 +++++++++++++++++ docs/theory/CROSS_CULTURAL_PERSPECTIVES.md | 485 ------------------- llm-warmup-dev.adoc | 19 + llm-warmup-dev.md | 20 - llm-warmup-user.adoc | 19 + llm-warmup-user.md | 20 - 26 files changed, 2344 insertions(+), 2532 deletions(-) rename ABI-FFI-README.md => ABI-FFI-README.adoc (74%) create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md delete mode 100644 GOVERNANCE.md create mode 100644 PROOF-NEEDS.adoc delete mode 100644 PROOF-NEEDS.md create mode 100644 README.adoc delete mode 100644 README.md create mode 100644 REQUIRES_INITIALISATION.adoc delete mode 100644 REQUIRES_INITIALISATION.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%) create mode 100644 docs/theory/AXIOLOGY_FOUNDATIONS.adoc delete mode 100644 docs/theory/AXIOLOGY_FOUNDATIONS.md create mode 100644 docs/theory/CROSS_CULTURAL_PERSPECTIVES.adoc delete mode 100644 docs/theory/CROSS_CULTURAL_PERSPECTIVES.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/ABI-FFI-README.md b/ABI-FFI-README.adoc similarity index 74% rename from ABI-FFI-README.md rename to ABI-FFI-README.adoc index 1606d48..32ce44d 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.adoc @@ -1,23 +1,22 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# AXIOLOGY_JL ABI/FFI Documentation +== AXIOLOGY_JL 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/ │ @@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, AffineScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── affinescript/ └── 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 @@ -101,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 @@ -115,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 @@ -129,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 { @@ -144,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 @@ -219,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() { @@ -241,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 AXIOLOGY_JL.ABI.Foreign main : IO () @@ -263,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; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,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 @@ -346,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/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..9111de0 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +Axiology.Jl 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* |j.d.a.jewell@open.ac.uk |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* j.d.a.jewell@open.ac.uk 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/Axiology.jl/discussions[Discussion] +(for general questions) +* Email j.d.a.jewell@open.ac.uk (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/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 65f800c..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,331 +0,0 @@ - -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Axiology.Jl 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** | j.d.a.jewell@open.ac.uk | 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** j.d.a.jewell@open.ac.uk 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/Axiology.jl/discussions) (for general questions) -- Email j.d.a.jewell@open.ac.uk (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/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..4db971a --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/Axiology.jl.git cd +Axiology.jl + +== Using Guix (recommended for reproducibility) + +guix develop + +== Or using toolbox/distrobox + +toolbox create Axiology.jl-dev toolbox enter Axiology.jl-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +Axiology.jl/ ├── 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.guix # Guix +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/Axiology.jl/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/Axiology.jl/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/Axiology.jl/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/Axiology.jl/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 d6b8ee4..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/Axiology.jl.git -cd Axiology.jl - -# Using Guix (recommended for reproducibility) -guix develop - -# Or using toolbox/distrobox -toolbox create Axiology.jl-dev -toolbox enter Axiology.jl-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -Axiology.jl/ -├── 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.guix # Guix 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/Axiology.jl/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/Axiology.jl/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/Axiology.jl/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/Axiology.jl/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 index e41020d..9b836fb 100644 --- a/GOVERNANCE.adoc +++ b/GOVERNANCE.adoc @@ -1,162 +1,60 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Governance Model -:toc: preamble +== Governance -This document describes the governance model for this repository. +=== Overview -== Overview +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. -This repository follows a **Sole Maintainer Governance Model**: +=== Roles and Responsibilities -* Single maintainer (@hyperpolymath) has full authority over the project -* All contributions are welcome and reviewed by the maintainer -* Decisions are made transparently through GitHub issues and discussions -* The project adheres to the hyperpolymath estate policies where applicable +==== Maintainers -== Core Principles +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 -[cols="1,2"] -|=== -| Principle | Description +==== Contributors -| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input +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 -| **Meritocracy** | Contributions are judged on technical merit, not contributor identity +=== Decision Making -| **Transparency** | All significant decisions are documented publicly +==== Minor Changes -| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates -| **Open Contribution** | Anyone can contribute via fork and pull request +==== Major Changes -|=== +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers -== Roles and Permissions +==== Breaking Changes -[cols="1,2,2"] -|=== -| Role | Permissions | Assignment +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide -| **Maintainer** | Write access, merge rights, admin | @hyperpolymath -| **Contributors** | Read access, fork, submit PRs | All GitHub users -| **Users** | Use the software, report issues | All GitHub users +=== Code of Conduct -|=== +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. -== Decision Making Framework +=== Communication -=== Routine Decisions +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions -* Bug fixes -* Documentation improvements -* Minor feature additions -* Dependency updates +=== Licensing -**Process**: Maintainer reviews and merges PRs that meet quality standards. +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. -=== Significant Changes +''''' -* New major features -* API changes -* Architecture modifications -* Breaking changes - -**Process**: -. Open issue describing the change -. Discuss with community (minimum 72 hours) -. Maintainer makes final decision -. Document rationale in issue/PR - -=== Structural Decisions - -* Repository purpose/renaming -* License changes -* Ownership transfer -* Deprecation/archival - -**Process**: -. Extended discussion (minimum 1 week) -. Maintainer makes final decision -. Document in CHANGELOG and governance docs - -== Contribution Lifecycle - -[cols="1,2"] -|=== -| Stage | Process - -| **Ideation** | Open issue, discuss feasibility - -| **Development** | Fork, implement, test thoroughly - -| **Review** | Submit PR, maintainer reviews within 7 days - -| **Merge** | Maintainer merges or requests changes - -| **Release** | Maintainer publishes according to project conventions - -|=== - -== Conflict Resolution - -In case of disagreements: - -. Discuss in the relevant GitHub issue or PR -. Provide technical justification for positions -. Maintainer mediates and makes final decision -. Decision is documented and can be revisited later - -== Project Policies - -This repository adheres to hyperpolymath estate-wide policies: - -* **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc) -* **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md -* **Security**: Follows hyperpolymath SECURITY.md -* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions - -== Repository-Specific Conventions - -[cols="1,2"] -|=== -| Convention | Description - -| **Signing** | All commits must be signed (SSH or GPG) - -| **SPDX Headers** | All source files must have SPDX license identifiers - -| **Contractiles** | Mustfile, Trustfile, Intendfile, Adjustfile in root - -| **Machine Readable** | META.a2ml in .machine_readable/6a2/ - -| **CI/CD** | GitHub Actions workflows in .github/workflows/ - -|=== - -== Governance Evolution - -As the project grows, this governance model may evolve: - -* **Adding Co-Maintainers**: When contribution volume warrants it -* **Forming a Team**: For complex multi-maintainer projects -* **Adopting TPCF**: For large, multi-repository projects (see rhodium-standard-repositories) - -Changes to this document require the same process as Significant Changes above. - -== See Also - -* link:MAINTAINERS.adoc[Maintainers] -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] -* link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy] -* link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)] - -== Changelog - -[cols="1,1,1"] -|=== -| Date | Change | By - -| 2026-06-07 | Initial governance model established | @hyperpolymath -|=== +_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..c28be14 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,13 @@ +== 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 +AXIOLOGY_JL/Jonathan D.A. Jewell 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 442f73d..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,14 +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 AXIOLOGY_JL/Jonathan D.A. Jewell 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/README.adoc b/README.adoc new file mode 100644 index 0000000..bdbaf37 --- /dev/null +++ b/README.adoc @@ -0,0 +1,326 @@ +https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/Axiology.jl[image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF +Best Practices]] +https://www.mozilla.org/MPL/2.0/[image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: +MPL-2.0]] + +== Overview + +*Axiology.jl* is a fully functional Julia library for value theory in +machine learning and automated reasoning systems. + +link:TOPOLOGY.md[image:https://img.shields.io/badge/Project-Topology-9558B2[Topology]] +link:TOPOLOGY.md[image:https://img.shields.io/badge/Completion-65%25-yellow[65]] + +> *Status*: ✅ *Alpha - Core value system functional, integration APIs +planned* - 1,088 lines of code, 43/45 tests passing + +> Axiology (from Greek ἀξία _axiā_ "`value`") is the philosophical study +of value. This library brings axiology into computational form, enabling +ML systems to reason about and verify value-aligned behavior. + +== The Value Alignment Problem + +Machine learning systems optimize objective functions, but: + +* *Misalignment Risk*: Optimizing the wrong metric leads to harmful +behavior +* *Multi-Objective Tradeoffs*: Real systems balance competing values +(fairness, efficiency, safety) +* *Implicit Values*: ML decisions encode ethical choices whether +acknowledged or not + +Axiology.jl makes values *explicit, verifiable, and composable*. + +== Core Concepts + +=== Value Types + +Axiology.jl provides a hierarchy of value types: + +[source,julia] +---- +abstract type Value end + +struct Fairness <: Value end +struct Welfare <: Value end +struct Profit <: Value end +struct Efficiency <: Value end +struct Safety <: Value end +---- + +=== Value Operations + +*Satisfy*: Check if a system state satisfies a value criterion + +[source,julia] +---- +satisfy(value::Value, state::SystemState) -> Bool +---- + +*Maximize*: Optimize a system to maximize a value + +[source,julia] +---- +maximize(value::Value, system::System) -> OptimizedSystem +---- + +*Verify*: Formally verify value alignment + +[source,julia] +---- +verify_value(value::Value, proof::Proof) -> Verified | Failed +---- + +== Installation + +From Julia REPL: + +[source,julia] +---- +using Pkg +Pkg.add("Axiology") +---- + +== Usage Examples + +=== Fairness-Aware ML + +[source,julia] +---- +using Axiology, MLJ + +# Define fairness criterion +fairness = Fairness( + protected_attribute = :gender, + metric = :demographic_parity, + threshold = 0.05 # Max 5% disparity +) + +# Train model with fairness constraint +model = train(algorithm, data, constraints=[fairness]) + +# Verify fairness post-hoc +@assert satisfy(fairness, model) +---- + +=== Multi-Objective Optimization + +[source,julia] +---- +using Axiology + +# Define competing values +values = [ + Welfare(metric=:utility_sum, weight=0.4), + Fairness(metric=:gini_coefficient, weight=0.3), + Efficiency(metric=:computation_time, weight=0.3) +] + +# Pareto-optimal solutions +solutions = pareto_frontier(system, values) + +# Select solution with value tradeoff +chosen = select_solution(solutions, preference=:balanced) +---- + +=== Formal Value Verification + +[source,julia] +---- +using Axiology, ECHIDNA + +# Define value invariant +safety = Safety( + invariant = "∀ state. system(state) ⟹ safe(state)", + prover = :Lean +) + +# Generate formal proof +proof = prove(safety.invariant, system) + +# Verify with theorem prover +verification = verify_value(safety, proof) + +if verification isa Verified + println("System formally proven safe ✓") +else + println("Safety violation: $(verification.counterexample)") +end +---- + +== API Reference + +=== Value Types + +`+Fairness+` + +Encodes fairness criteria (demographic parity, equalized odds, etc.) + +`+Welfare+` + +Utilitarian welfare measures (sum, mean, or weighted utility) + +`+Profit+` + +Economic value (revenue, cost, ROI) + +`+Efficiency+` + +Resource efficiency (time, memory, energy) + +`+Safety+` + +Safety constraints (invariants, preconditions, postconditions) + +=== Core Functions + +`+satisfy(value,+` `+state)+` `+→+` `+Bool+` + +Check if `+state+` satisfies `+value+` criterion. + +`+maximize(value,+` `+system)+` `+→+` `+OptimizedSystem+` + +Optimize `+system+` to maximize `+value+` while preserving constraints. + +`+verify_value(value,+` `+proof)+` `+→+` `+Verified+` `+|+` `+Failed+` + +Formally verify that `+proof+` demonstrates value alignment. + +`+pareto_frontier(system,+` `+values)+` `+→+` `+Vector{Solution}+` + +Compute Pareto-optimal solutions for multi-objective value optimization. + +`+select_solution(solutions,+` `+preference)+` `+→+` `+Solution+` + +Select solution from Pareto frontier based on value preferences. + +== Theoretical Foundations + +Axiology.jl draws from: + +* *Moral Philosophy*: Utilitarianism, deontology, virtue ethics +* *Welfare Economics*: Pareto efficiency, social welfare functions +* *Game Theory*: Nash equilibria, cooperative games, mechanism design +* *Formal Methods*: Model checking, theorem proving, contract +verification +* *ML Fairness*: Demographic parity, equalized odds, individual fairness + +== Integration with ECHIDNA + +Axiology.jl is designed for tight integration with ECHIDNA: + +* *Formal Verification*: Use ECHIDNA’s 17 theorem provers to verify +value invariants +* *Neural Guidance*: Train ML models to predict value-aligned actions +* *Multi-Prover Consensus*: Cross-validate value proofs across multiple +provers +* *Explainability*: Generate natural language explanations of value +tradeoffs + +=== Example: Verified Fairness + +[source,julia] +---- +using Axiology, ECHIDNA + +# Define fairness as formal invariant +fairness = Fairness( + invariant = "∀ (x₁ x₂ : Input). + protected_attr(x₁) ≠ protected_attr(x₂) ⟹ + |P(Ŷ=1|X=x₁) - P(Ŷ=1|X=x₂)| < ε", + prover = :Lean +) + +# Generate proof with ECHIDNA +proof = ECHIDNA.prove(fairness.invariant, + model=my_classifier, + prover=:Lean) + +# Verify +result = verify_value(fairness, proof) +---- + +== Development Status + +Current Version: *0.1.0* (Initial Release) + +* [x] Core value type hierarchy +* [x] Basic satisfy/maximize/verify API +* [x] Initial test suite +* [x] RSR compliance +* [ ] Multi-objective optimization +* [ ] Formal verification integration with ECHIDNA +* [ ] ML fairness library integration (FairLearn, AIF360) +* [ ] Comprehensive documentation + +See ROADMAP for development plans. + +== Use Cases + +=== Healthcare AI + +* *Safety*: Verify medical AI never recommends contraindicated +treatments +* *Fairness*: Ensure diagnostic models don’t discriminate by race/gender +* *Welfare*: Optimize for patient outcomes, not just hospital metrics + +=== Financial Systems + +* *Fairness*: Prevent algorithmic discrimination in lending +* *Profit*: Balance returns with stakeholder welfare +* *Efficiency*: Optimize execution speed without market manipulation + +=== Autonomous Vehicles + +* *Safety*: Formally prove collision avoidance under all conditions +* *Welfare*: Balance passenger and pedestrian safety +* *Efficiency*: Optimize routes without compromising safety + +=== Public Policy + +* *Welfare*: Evaluate policy impact with social welfare functions +* *Fairness*: Detect and mitigate disparate impact +* *Efficiency*: Balance effectiveness with resource constraints + +== License + +Dual licensed under: + +* *MIT License* - LICENSE-MIT +* *Palimpsest Meta-Project License 1.0* - LICENSE-PMPL + +Choose either license for use, modification, and distribution. + +== Contributing + +See CONTRIBUTING for contribution guidelines. + +Priority areas: + +* *Formal Methods*: Integration with Lean, Coq, Isabelle +* *ML Fairness*: Wrappers for existing fairness libraries +* *Case Studies*: Real-world value alignment applications +* *Visualization*: Tools for value tradeoff exploration + +== Citation + +If you use Axiology.jl in research, please cite: + +[source,bibtex] +---- +@software{axiology2026, + author = {Jewell, Jonathan D.A.}, + title = {Axiology.jl: Value Theory for Machine Learning}, + year = {2026}, + version = {0.1.0}, + url = {https://github.com/hyperpolymath/Axiology.jl} +} +---- + +== References + +* *AI Alignment*: Russell, S. (2019). _Human Compatible: AI and the +Problem of Control_ +* *ML Fairness*: Barocas, S., Hardt, M., & Narayanan, A. (2023). +_Fairness and Machine Learning_ +* *Formal Methods*: Hoare, T. (1969). "`An Axiomatic Basis for Computer +Programming`" +* *Value Theory*: Korsgaard, C. (1983). "`Two Distinctions in Goodness`" +* *Welfare Economics*: Sen, A. (1970). _Collective Choice and Social +Welfare_ + +== Contact + +* *Author:* Jonathan D.A. Jewell +* *GitHub:* https://github.com/hyperpolymath/Axiology.jl +* *Issues:* https://github.com/hyperpolymath/Axiology.jl/issues diff --git a/README.md b/README.md deleted file mode 100644 index 8012de0..0000000 --- a/README.md +++ /dev/null @@ -1,361 +0,0 @@ - - -[![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity)](https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/Axiology.jl) -[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://www.mozilla.org/MPL/2.0/) - - -# Overview - -**Axiology.jl** is a fully functional Julia library for value theory in -machine learning and automated reasoning systems. - -[![Topology](https://img.shields.io/badge/Project-Topology-9558B2)](TOPOLOGY.md) -[![65](https://img.shields.io/badge/Completion-65%25-yellow)](TOPOLOGY.md) - -\> **Status**: ✅ **Alpha - Core value system functional, integration -APIs planned** - 1,088 lines of code, 43/45 tests passing - -\> Axiology (from Greek ἀξία *axiā* "value") is the philosophical study -of value. This library brings axiology into computational form, enabling -ML systems to reason about and verify value-aligned behavior. - -# The Value Alignment Problem - -Machine learning systems optimize objective functions, but: - -- **Misalignment Risk**: Optimizing the wrong metric leads to harmful - behavior - -- **Multi-Objective Tradeoffs**: Real systems balance competing values - (fairness, efficiency, safety) - -- **Implicit Values**: ML decisions encode ethical choices whether - acknowledged or not - -Axiology.jl makes values **explicit, verifiable, and composable**. - -# Core Concepts - -## Value Types - -Axiology.jl provides a hierarchy of value types: - -```julia -abstract type Value end - -struct Fairness <: Value end -struct Welfare <: Value end -struct Profit <: Value end -struct Efficiency <: Value end -struct Safety <: Value end -``` - -## Value Operations - -**Satisfy**: Check if a system state satisfies a value criterion - -```julia -satisfy(value::Value, state::SystemState) -> Bool -``` - -**Maximize**: Optimize a system to maximize a value - -```julia -maximize(value::Value, system::System) -> OptimizedSystem -``` - -**Verify**: Formally verify value alignment - -```julia -verify_value(value::Value, proof::Proof) -> Verified | Failed -``` - -# Installation - -From Julia REPL: - -```julia -using Pkg -Pkg.add("Axiology") -``` - -# Usage Examples - -## Fairness-Aware ML - -```julia -using Axiology, MLJ - -# Define fairness criterion -fairness = Fairness( - protected_attribute = :gender, - metric = :demographic_parity, - threshold = 0.05 # Max 5% disparity -) - -# Train model with fairness constraint -model = train(algorithm, data, constraints=[fairness]) - -# Verify fairness post-hoc -@assert satisfy(fairness, model) -``` - -## Multi-Objective Optimization - -```julia -using Axiology - -# Define competing values -values = [ - Welfare(metric=:utility_sum, weight=0.4), - Fairness(metric=:gini_coefficient, weight=0.3), - Efficiency(metric=:computation_time, weight=0.3) -] - -# Pareto-optimal solutions -solutions = pareto_frontier(system, values) - -# Select solution with value tradeoff -chosen = select_solution(solutions, preference=:balanced) -``` - -## Formal Value Verification - -```julia -using Axiology, ECHIDNA - -# Define value invariant -safety = Safety( - invariant = "∀ state. system(state) ⟹ safe(state)", - prover = :Lean -) - -# Generate formal proof -proof = prove(safety.invariant, system) - -# Verify with theorem prover -verification = verify_value(safety, proof) - -if verification isa Verified - println("System formally proven safe ✓") -else - println("Safety violation: $(verification.counterexample)") -end -``` - -# API Reference - -## Value Types - -`Fairness` -Encodes fairness criteria (demographic parity, equalized odds, etc.) - -`Welfare` -Utilitarian welfare measures (sum, mean, or weighted utility) - -`Profit` -Economic value (revenue, cost, ROI) - -`Efficiency` -Resource efficiency (time, memory, energy) - -`Safety` -Safety constraints (invariants, preconditions, postconditions) - -## Core Functions - -`satisfy(value,` `state)` `→` `Bool` -Check if `state` satisfies `value` criterion. - -`maximize(value,` `system)` `→` `OptimizedSystem` -Optimize `system` to maximize `value` while preserving constraints. - -`verify_value(value,` `proof)` `→` `Verified` `|` `Failed` -Formally verify that `proof` demonstrates value alignment. - -`pareto_frontier(system,` `values)` `→` `Vector{Solution}` -Compute Pareto-optimal solutions for multi-objective value optimization. - -`select_solution(solutions,` `preference)` `→` `Solution` -Select solution from Pareto frontier based on value preferences. - -# Theoretical Foundations - -Axiology.jl draws from: - -- **Moral Philosophy**: Utilitarianism, deontology, virtue ethics - -- **Welfare Economics**: Pareto efficiency, social welfare functions - -- **Game Theory**: Nash equilibria, cooperative games, mechanism design - -- **Formal Methods**: Model checking, theorem proving, contract - verification - -- **ML Fairness**: Demographic parity, equalized odds, individual - fairness - -# Integration with ECHIDNA - -Axiology.jl is designed for tight integration with ECHIDNA: - -- **Formal Verification**: Use ECHIDNA’s 17 theorem provers to verify - value invariants - -- **Neural Guidance**: Train ML models to predict value-aligned actions - -- **Multi-Prover Consensus**: Cross-validate value proofs across - multiple provers - -- **Explainability**: Generate natural language explanations of value - tradeoffs - -## Example: Verified Fairness - -```julia -using Axiology, ECHIDNA - -# Define fairness as formal invariant -fairness = Fairness( - invariant = "∀ (x₁ x₂ : Input). - protected_attr(x₁) ≠ protected_attr(x₂) ⟹ - |P(Ŷ=1|X=x₁) - P(Ŷ=1|X=x₂)| < ε", - prover = :Lean -) - -# Generate proof with ECHIDNA -proof = ECHIDNA.prove(fairness.invariant, - model=my_classifier, - prover=:Lean) - -# Verify -result = verify_value(fairness, proof) -``` - -# Development Status - -Current Version: **0.1.0** (Initial Release) - -- [x] Core value type hierarchy - -- [x] Basic satisfy/maximize/verify API - -- [x] Initial test suite - -- [x] RSR compliance - -- [ ] Multi-objective optimization - -- [ ] Formal verification integration with ECHIDNA - -- [ ] ML fairness library integration (FairLearn, AIF360) - -- [ ] Comprehensive documentation - -See ROADMAP for development -plans. - -# Use Cases - -## Healthcare AI - -- **Safety**: Verify medical AI never recommends contraindicated - treatments - -- **Fairness**: Ensure diagnostic models don’t discriminate by - race/gender - -- **Welfare**: Optimize for patient outcomes, not just hospital metrics - -## Financial Systems - -- **Fairness**: Prevent algorithmic discrimination in lending - -- **Profit**: Balance returns with stakeholder welfare - -- **Efficiency**: Optimize execution speed without market manipulation - -## Autonomous Vehicles - -- **Safety**: Formally prove collision avoidance under all conditions - -- **Welfare**: Balance passenger and pedestrian safety - -- **Efficiency**: Optimize routes without compromising safety - -## Public Policy - -- **Welfare**: Evaluate policy impact with social welfare functions - -- **Fairness**: Detect and mitigate disparate impact - -- **Efficiency**: Balance effectiveness with resource constraints - -# License - -Dual licensed under: - -- **MIT License** - [LICENSE-MIT](LICENSE-MIT) - -- **Palimpsest Meta-Project License 1.0** - [LICENSE-PMPL](LICENSE-PMPL) - -Choose either license for use, modification, and distribution. - -# Contributing - -See CONTRIBUTING for -contribution guidelines. - -Priority areas: - -- **Formal Methods**: Integration with Lean, Coq, Isabelle - -- **ML Fairness**: Wrappers for existing fairness libraries - -- **Case Studies**: Real-world value alignment applications - -- **Visualization**: Tools for value tradeoff exploration - -# Citation - -If you use Axiology.jl in research, please cite: - -```bibtex -@software{axiology2026, - author = {Jewell, Jonathan D.A.}, - title = {Axiology.jl: Value Theory for Machine Learning}, - year = {2026}, - version = {0.1.0}, - url = {https://github.com/hyperpolymath/Axiology.jl} -} -``` - -# References - -- **AI Alignment**: Russell, S. (2019). *Human Compatible: AI and the - Problem of Control* - -- **ML Fairness**: Barocas, S., Hardt, M., & Narayanan, A. (2023). - *Fairness and Machine Learning* - -- **Formal Methods**: Hoare, T. (1969). "An Axiomatic Basis for Computer - Programming" - -- **Value Theory**: Korsgaard, C. (1983). "Two Distinctions in Goodness" - -- **Welfare Economics**: Sen, A. (1970). *Collective Choice and Social - Welfare* - -# Contact - -- **Author:** Jonathan D.A. Jewell - \<[j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk\> - -- **GitHub:** - -- **Issues:** diff --git a/REQUIRES_INITIALISATION.adoc b/REQUIRES_INITIALISATION.adoc new file mode 100644 index 0000000..1fd9246 --- /dev/null +++ b/REQUIRES_INITIALISATION.adoc @@ -0,0 +1,92 @@ +== REQUIRES INITIALISATION + +*This repository is not finished being set up.* 5 substitution token(s) +across 3 file(s) still have no value. + +=== Why this is not already done + +This repo was created from `+hyperpolymath/rsr-template-repo+`. The mint +(`+just repo-init+`) fills every token that has a single mechanical +answer — owner, repo, author, dates, licence, branch — and it has done +so here. + +The tokens below are the ones it _deliberately cannot_ answer. They need +a decision or a fact that exists only in your head: what this project is +for, what command builds it, which port the service listens on, whether +a PGP key is held at all. The template’s own token vocabulary says as +much — you cannot sensibly answer "`required invariants`" in a +thirty-second bootstrap. + +They were left *visibly unfilled on purpose*. The alternatives were both +worse: inventing plausible values would put confident falsehoods into a +security policy and an architecture document, and silently deleting the +sections would hide the fact that a decision is owed. A visible gap is +honest; a fabricated answer is not. + +=== Do not delete this file until every item below is resolved + +This file is the only marker that the work is outstanding. Deleting it +early does not finish the setup, it just conceals it — and the next +person or agent to arrive will reasonably assume the repo is complete. + +* *If you are a person:* delete this file yourself once the last item is +done. +* *If you are an agent:* resolve what you legitimately can, leave the +rest, and delete this file only when no token below remains anywhere in +the tree. Do not delete it to make a gate go green. + +Re-running the estate top-up tool will remove this file automatically +once nothing is outstanding, so the safest way to finish is to fix the +tokens and let the check confirm it. + +=== What is needed, and where it goes + +==== `+{{CONDUCT_TEAM}}+` + +Name of the conduct body. If there is no committee, rewrite the sentence +rather than substituting a plural noun into '`a \{\{CONDUCT_TEAM}} +member`'. + +Appears in: + +* `+CODE_OF_CONDUCT.md+` + +==== `+{{PGP_KEY_URL}}+` + +Public URL the PGP key can be fetched from. Same caveat as +PGP_FINGERPRINT. + +Appears in: + +* `+SECURITY.md+` + +==== `+{{PROJECT_UNIQUE_STRENGTH}}+` + +What this does that its alternatives do not. + +Appears in: + +* `+.machine_readable/bot_directives/methodology.a2ml+` + +==== `+{{RESPONSE_TIME}}+` + +Initial-response SLA for a security or conduct report. Promise only what +a solo maintainer can actually meet. + +Appears in: + +* `+CODE_OF_CONDUCT.md+` + +==== `+{{WEBSITE}}+` + +Project homepage URL, or delete the field if there is none. + +Appears in: + +* `+SECURITY.md+` + +''''' + +Generated by the estate top-up pass. Rationale and the governing rulings +are in `+hyperpolymath/standards+`; the token vocabulary is +`+.machine_readable/ai/PLACEHOLDERS.adoc+` in `+rsr-template-repo+`. diff --git a/REQUIRES_INITIALISATION.md b/REQUIRES_INITIALISATION.md deleted file mode 100644 index f1a4f66..0000000 --- a/REQUIRES_INITIALISATION.md +++ /dev/null @@ -1,86 +0,0 @@ - - -# REQUIRES INITIALISATION - -**This repository is not finished being set up.** 5 substitution token(s) across 3 file(s) still have no value. - -## Why this is not already done - -This repo was created from `hyperpolymath/rsr-template-repo`. The mint -(`just repo-init`) fills every token that has a single mechanical answer — -owner, repo, author, dates, licence, branch — and it has done so here. - -The tokens below are the ones it *deliberately cannot* answer. They need a -decision or a fact that exists only in your head: what this project is for, -what command builds it, which port the service listens on, whether a PGP key -is held at all. The template's own token vocabulary says as much — you cannot -sensibly answer "required invariants" in a thirty-second bootstrap. - -They were left **visibly unfilled on purpose**. The alternatives were both -worse: inventing plausible values would put confident falsehoods into a -security policy and an architecture document, and silently deleting the -sections would hide the fact that a decision is owed. A visible gap is -honest; a fabricated answer is not. - -## Do not delete this file until every item below is resolved - -This file is the only marker that the work is outstanding. Deleting it early -does not finish the setup, it just conceals it — and the next person or agent -to arrive will reasonably assume the repo is complete. - -- **If you are a person:** delete this file yourself once the last item is done. -- **If you are an agent:** resolve what you legitimately can, leave the rest, - and delete this file only when no token below remains anywhere in the tree. - Do not delete it to make a gate go green. - -Re-running the estate top-up tool will remove this file automatically once -nothing is outstanding, so the safest way to finish is to fix the tokens and -let the check confirm it. - -## What is needed, and where it goes - -### `{{CONDUCT_TEAM}}` - -Name of the conduct body. If there is no committee, rewrite the sentence rather than substituting a plural noun into 'a {{CONDUCT_TEAM}} member'. - -Appears in: - -- `CODE_OF_CONDUCT.md` - -### `{{PGP_KEY_URL}}` - -Public URL the PGP key can be fetched from. Same caveat as PGP_FINGERPRINT. - -Appears in: - -- `SECURITY.md` - -### `{{PROJECT_UNIQUE_STRENGTH}}` - -What this does that its alternatives do not. - -Appears in: - -- `.machine_readable/bot_directives/methodology.a2ml` - -### `{{RESPONSE_TIME}}` - -Initial-response SLA for a security or conduct report. Promise only what a solo maintainer can actually meet. - -Appears in: - -- `CODE_OF_CONDUCT.md` - -### `{{WEBSITE}}` - -Project homepage URL, or delete the field if there is none. - -Appears in: - -- `SECURITY.md` - ---- - -Generated by the estate top-up pass. Rationale and the governing rulings are -in `hyperpolymath/standards`; the token vocabulary is -`.machine_readable/ai/PLACEHOLDERS.adoc` in `rsr-template-repo`. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..448b3b8 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,452 @@ +== 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 + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[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: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/Axiology.jl/security/advisories/new[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: + +[cols=",",] +|=== +|*Email* |6759885+hyperpolymath@users.noreply.github.com +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+[PGP fingerprint not set]+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint 6759885+hyperpolymath@users.noreply.github.com + +# Encrypt your report +gpg --armor --encrypt --recipient 6759885+hyperpolymath@users.noreply.github.com 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 +https://www.first.org/cvss/calculator/3.1[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 + +[source,markdown] +---- +## 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: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|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): + +[arabic] +. *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/Axiology.jl+`) 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 +link:SECURITY-ACKNOWLEDGMENTS.md[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 +https://github.com/hyperpolymath/Axiology.jl/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|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 + +[cols=",,",options="header",] +|=== +|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 Axiology.Jl, 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 + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/hyperpolymath/Axiology.jl/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/Axiology.jl/security/advisories/new[Report +via GitHub] or 6759885+hyperpolymath@users.noreply.github.com + +|*General questions* +|https://github.com/hyperpolymath/Axiology.jl/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[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 Axiology.Jl and its users safe._ 🛡️ + +''''' + +Last updated: 2026 · Policy version: 1.0.0 diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index f503b7a..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,410 +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](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#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: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/Axiology.jl/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. 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** | 6759885+hyperpolymath@users.noreply.github.com | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `[PGP fingerprint not set]` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint 6759885+hyperpolymath@users.noreply.github.com - -# Encrypt your report -gpg --armor --encrypt --recipient 6759885+hyperpolymath@users.noreply.github.com 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](https://www.first.org/cvss/calculator/3.1)) -- **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 - -```markdown -## 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): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **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/Axiology.jl`) 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](SECURITY-ACKNOWLEDGMENTS.md) (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](https://github.com/hyperpolymath/Axiology.jl/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### 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 Axiology.Jl, 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]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/hyperpolymath/Axiology.jl/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/Axiology.jl/security/advisories/new) or 6759885+hyperpolymath@users.noreply.github.com | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/Axiology.jl/discussions) | -| **Other enquiries** | See [README](README.md) 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 Axiology.Jl and its users safe.* 🛡️ - ---- - -Last updated: 2026 · Policy version: 1.0.0 diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..573815c --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,32 @@ +== TEST-NEEDS.md — Axiology.jl + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Test directories |2 |Location(s): /test, /tests +|CI workflows |19 |Running tests on GitHub Actions +|Unit tests |Built-in |Julia test framework +|=== + +=== What’s Covered + +* [x] Julia unit tests (Pkg.test()) +* [x] Module doctests + +=== Still Missing (for CRG B+) + +* [ ] Code coverage reports (codecov integration) +* [ ] Detailed test documentation in CONTRIBUTING.md +* [ ] Integration tests beyond unit tests +* [ ] Performance benchmarking suite + +=== Run Tests + +[source,bash] +---- +julia --project -e 'using Pkg; Pkg.test()' +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index efa3ae9..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,33 +0,0 @@ - -# TEST-NEEDS.md — Axiology.jl - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Test directories | 2 | Location(s): /test, /tests | -| CI workflows | 19 | Running tests on GitHub Actions | -| Unit tests | Built-in | Julia test framework | - -## What's Covered - -- [x] Julia unit tests (Pkg.test()) -- [x] Module doctests - -## Still Missing (for CRG B+) - -- [ ] Code coverage reports (codecov integration) -- [ ] Detailed test documentation in CONTRIBUTING.md -- [ ] Integration tests beyond unit tests -- [ ] Performance benchmarking suite - -## Run Tests - -```bash -julia --project -e 'using Pkg; Pkg.test()' -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 87% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 11bb2af..d3cee45 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== Axiology.jl — Project Topology -# Axiology.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -46,11 +39,11 @@ Copyright (c) Jonathan D.A. Jewell │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE LOGIC @@ -68,26 +61,27 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████░░░░ ~65% Core value system functional -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Type Definitions ──────► Satisfy Check ──────► Optimization (Maximize) │ ┌─────────┴─────────┐ ▼ ▼ ML Integration Formal Verification -``` +.... -## 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/docs/theory/AXIOLOGY_FOUNDATIONS.adoc b/docs/theory/AXIOLOGY_FOUNDATIONS.adoc new file mode 100644 index 0000000..aa361b0 --- /dev/null +++ b/docs/theory/AXIOLOGY_FOUNDATIONS.adoc @@ -0,0 +1,320 @@ +== Axiology: Theoretical Foundations + +=== Etymology and Cross-Linguistic Analysis + +==== Ancient Greek Origins + +*Axiology* derives from two Ancient Greek roots: - *ἀξία* (_axiā_) - +"`value, worth`" (from ἄξιος _axios_ - "`worthy`") - *-λογία* (_-logia_) +- "`study of, discourse`" (from λόγος _logos_) + +The term was coined in *1902* by French philosopher *Paul Lapie* and +independently by *Eduard von Hartmann* (German: _Axiologie_) to describe +the systematic philosophical study of value. + +==== Cross-Linguistic Terminology + +[cols=",,",options="header",] +|=== +|Language |Term |Literal Meaning +|*Greek* |Αξιολογία (_Axiología_) |Value-study (original) +|*Latin* |_Scientia valoris_ |Science of value +|*German* |_Axiologie_ / _Wertlehre_ |Value-theory +|*French* |_Axiologie_ / _Théorie de la valeur_ |Value-theory +|*Russian* |Аксиология (_Aksiologiya_) |Axiology +|*Japanese* |価値論 (_Kachironnot_) |Value-theory +|*Chinese* |价值论 (_Jiàzhílùn_) |Value-theory +|*Arabic* |علم القيم (_’Ilm al-Qiyam_) |Science of values +|*Sanskrit* |मूल्य-विज्ञान (_Mūlya-vijñāna_) |Value-knowledge +|=== + +''''' + +=== Historical Development + +==== Ancient Antecedents (Before "`Axiology`") + +===== Greek Philosophy (5th-3rd century BCE) + +*Socrates* (470-399 BCE): - Questioned conventional values ("`What is +the good?`") - Introduced value-inquiry as central to philosophy - +_"`The unexamined life is not worth living`"_ - value of self-knowledge + +*Plato* (428-348 BCE): - _Theory of Forms_: Absolute values (Good, +Beautiful, Just) exist independently - _Republic_: Hierarchy of values +(wisdom > courage > temperance > justice) - _Form of the Good_ - +ultimate value, source of all other values + +*Aristotle* (384-322 BCE): - _Nicomachean Ethics_: Virtue as excellence +(_aretē_) - *Intrinsic vs. Instrumental Value*: Distinction between ends +and means - _Eudaimonia_ (flourishing) as highest human value + +===== Medieval Philosophy (4th-14th century CE) + +*Augustine of Hippo* (354-430 CE): - Christian values hierarchy: God +(highest) → soul → body → material goods - _De Doctrina Christiana_: +Things to be "`used`" (_uti_) vs. "`enjoyed`" (_frui_) + +*Thomas Aquinas* (1225-1274): - Natural Law theory: Universal values +grounded in human nature - Hierarchy of goods: Divine → intellectual → +physical + +===== Early Modern (16th-18th century) + +*David Hume* (1711-1776): - Is-Ought Problem: Can’t derive value +judgments from factual statements - Sentiment theory of value: Values +grounded in human sentiments + +*Immanuel Kant* (1724-1804): - *Categorical Imperative*: Persons have +absolute value (ends-in-themselves) - Moral worth independent of +consequences - Foundation for deontological ethics + +''''' + +==== Formal Axiology (1900-Present) + +===== Founding Era (1900-1920) + +*Eduard von Hartmann* (1842-1906): - _Grundriss der Axiologie_ (1909) - +Systematized value theory as distinct philosophical discipline + +*Paul Lapie* (1869-1927): - _Logique de la volonté_ (1902) - Coined +"`axiologie`" independently + +*Alexius Meinong* (1853-1920): - _Zur Grundlegung der allgemeinen +Werttheorie_ (1923) - Value as objective property of objects - +Value-feelings (_Wertgefühle_) vs. value-properties + +===== Phenomenological Axiology (1913-1928) + +*Max Scheler* (1874-1928): - _Der Formalismus in der Ethik_ (1913-1916) +- Values as _a priori_ intuited essences - *Hierarchy of Values* (low → +high): 1. Pleasant/unpleasant (sensory) 2. Noble/vulgar (vital) 3. +Spiritual values (intellectual, aesthetic, legal) 4. Holy/unholy +(religious) - Values known through emotional intuition (_Wertfühlen_) + +*Nicolai Hartmann* (1882-1950): - _Ethik_ (1926) - Objective value +realism: Values exist independently of subjects - Strength vs. Height: +Strong values (e.g., justice) vs. high values (e.g., love) + +===== Formal Axiology (1967-Present) + +*Robert S. Hartman* (1910-1973): - _The Structure of Value_ (1967) - +*Mathematical axiology*: Value as degree of concept-fulfillment - Three +dimensions of value: 1. *Systemic* (_S_): Conceptual perfection +(mathematics, logic) 2. *Extrinsic* (_E_): Practical utility (tools, +instruments) 3. *Intrinsic* (_I_): Unique worth (persons, art, +experiences) - Axiomatic value theory (18 axioms) + +''''' + +=== Contemporary Schools + +==== Value Realism + +*Position*: Values exist objectively, independent of human minds + +*Representatives*: - *G.E. Moore* (1873-1958): "`Good`" as non-natural +property - *Nicolai Hartmann*: Values as ideal essences - *David Brink*: +Moral realism, values as objective features + +*Arguments*: - Convergence: Cultures converge on basic values (e.g., +harm is bad) - Moral phenomenology: Values _seem_ objective - Best +explanation: Objectivity explains disagreement (we’re all trying to +discover truth) + +==== Value Subjectivism + +*Position*: Values are projections of human preferences/emotions + +*Representatives*: - *David Hume*: Sentimentalism - *A.J. Ayer*: +Emotivism - value statements are expressions of emotion - *Simon +Blackburn*: Quasi-realism + +*Arguments*: - Metaphysical parsimony: No need for strange "`value +properties`" - Diversity: Radical value disagreements across cultures - +Motivation: Values necessarily motivate → must be grounded in desires + +==== Value Constructivism + +*Position*: Values are constructed through social/rational procedures + +*Representatives*: - *John Rawls*: Justice as fair agreement behind +"`veil of ignorance`" - *Christine Korsgaard*: Kantian constructivism - +*Jürgen Habermas*: Discourse ethics + +*Arguments*: - Objectivity without metaphysics: Intersubjective +agreement - Respect for autonomy: Values we give ourselves - Democratic +legitimacy: Values emerge from dialogue + +''''' + +=== Axiology in Economics + +==== Classical Economics (18th-19th century) + +*Adam Smith* (1723-1790): - _The Wealth of Nations_ (1776) - +*Diamond-Water Paradox*: Diamonds (less useful) more valuable than water +- Use-value vs. exchange-value distinction + +*David Ricardo* (1772-1823): - Labor theory of value: Value derives from +labor input + +*Karl Marx* (1818-1883): - _Das Kapital_ (1867) - Exchange-value +vs. use-value - Critique: Capitalism treats labor as commodity + +==== Marginalist Revolution (1870s) + +*William Stanley Jevons*, *Carl Menger*, *Léon Walras*: - *Marginal +utility theory*: Value = utility of last unit consumed - Solved +diamond-water paradox: Water’s marginal utility is low (abundant) + +==== Welfare Economics (1900-Present) + +*Vilfredo Pareto* (1848-1923): - *Pareto efficiency*: No one can be made +better off without someone worse off - Foundation for modern welfare +analysis + +*John Hicks* & *Nicholas Kaldor* (1939): - *Kaldor-Hicks criterion*: +Compensation principle for policy evaluation + +*Amartya Sen* (1933-Present): - Nobel Prize 1998 - _Collective Choice +and Social Welfare_ (1970) - *Capability approach*: Value = capabilities +(freedoms) not just utility - Critique of utilitarianism: Ignores +distribution, adaptive preferences + +''''' + +=== Axiology in Computer Science & AI + +==== Decision Theory + +*John von Neumann* & *Oskar Morgenstern* (1944): - _Theory of Games and +Economic Behavior_ - *Expected utility theory*: Rational choice under +uncertainty - Axioms: Completeness, transitivity, continuity, +independence + +==== Preference Learning + +*Machine learning of value functions*: - Inverse reinforcement learning +(Ng & Russell, 2000) - Learning from human feedback (RLHF) - Preference +elicitation algorithms + +==== AI Alignment & Value Loading + +*Stuart Russell* (2019): - _Human Compatible: AI and the Problem of +Control_ - *Value alignment problem*: How to ensure AI optimizes human +values - Uncertainty about human values → provably beneficial AI + +*Nick Bostrom* (2014): - _Superintelligence_ - *Instrumental +convergence*: AIs converge on instrumental goals regardless of terminal +values - Paperclip maximizer thought experiment + +''''' + +=== Formal Representations + +==== Preference Relations + +Given set latexmath:[X] of alternatives, preference relation +latexmath:[\succsim] ("`at least as good as`"): + +*Properties*: - *Completeness*: +latexmath:[\forall x,y \in X: x \succsim y \lor y \succsim x] - +*Transitivity*: +latexmath:[x \succsim y \land y \succsim z \Rightarrow x \succsim z] - +*Reflexivity*: latexmath:[x \succsim x] + +*Strict preference*: +latexmath:[x \succ y \iff x \succsim y \land \neg(y \succsim x)] + +*Indifference*: +latexmath:[x \sim y \iff x \succsim y \land y \succsim x] + +==== Utility Functions + +*Representation theorem* (Debreu, 1954): If latexmath:[\succsim] is +complete, transitive, continuous, then latexmath:[\exists] utility +function latexmath:[u: X \to \mathbb{R}] such that: + +[latexmath] +++++ +x \succsim y \iff u(x) \geq u(y) +++++ + +*Ordinal utility*: Only order matters, not magnitude + +*Cardinal utility*: Magnitude differences are meaningful + +==== Social Welfare Functions + +*Aggregation*: latexmath:[n] individuals, utilities +latexmath:[u_1, \ldots, u_n] + +*Utilitarian* (Bentham): + +[latexmath] +++++ +W = \sum_{i=1}^n u_i +++++ + +*Rawlsian* (maximin): + +[latexmath] +++++ +W = \min_i u_i +++++ + +*Weighted sum*: + +[latexmath] +++++ +W = \sum_{i=1}^n w_i u_i, \quad \sum_i w_i = 1 +++++ + +*Nash* (product): + +[latexmath] +++++ +W = \prod_{i=1}^n u_i +++++ + +''''' + +=== Connections to This Library + +This implementation operationalizes: + +[arabic] +. *Classical axiology* → Type system (Fairness, Welfare, etc.) +. *Formal axiology* → Measurable value functions +. *Welfare economics* → Social welfare functions +. *AI alignment* → Verification of value satisfaction +. *Multi-criteria decision* → Pareto frontier analysis + +''''' + +=== References + +==== Primary Sources + +* Aristotle. (350 BCE). _Nicomachean Ethics_. +* Kant, I. (1785). _Groundwork of the Metaphysics of Morals_. +* Scheler, M. (1916). _Formalism in Ethics and Non-Formal Ethics of +Values_. +* Hartman, R.S. (1967). _The Structure of Value_. + +==== Contemporary + +* Sen, A. (1970). _Collective Choice and Social Welfare_. +* Rawls, J. (1971). _A Theory of Justice_. +* Bostrom, N. (2014). _Superintelligence_. +* Russell, S. (2019). _Human Compatible_. + +==== Technical + +* von Neumann, J., & Morgenstern, O. (1944). _Theory of Games and +Economic Behavior_. +* Arrow, K. (1951). _Social Choice and Individual Values_. +* Ng, A.Y., & Russell, S. (2000). "`Algorithms for Inverse Reinforcement +Learning`". diff --git a/docs/theory/AXIOLOGY_FOUNDATIONS.md b/docs/theory/AXIOLOGY_FOUNDATIONS.md deleted file mode 100644 index ad09a9d..0000000 --- a/docs/theory/AXIOLOGY_FOUNDATIONS.md +++ /dev/null @@ -1,316 +0,0 @@ - -# Axiology: Theoretical Foundations - -## Etymology and Cross-Linguistic Analysis - -### Ancient Greek Origins - -**Axiology** derives from two Ancient Greek roots: -- **ἀξία** (*axiā*) - "value, worth" (from ἄξιος *axios* - "worthy") -- **-λογία** (*-logia*) - "study of, discourse" (from λόγος *logos*) - -The term was coined in **1902** by French philosopher **Paul Lapie** and independently by **Eduard von Hartmann** (German: *Axiologie*) to describe the systematic philosophical study of value. - -### Cross-Linguistic Terminology - -| Language | Term | Literal Meaning | -|----------|------|-----------------| -| **Greek** | Αξιολογία (*Axiología*) | Value-study (original) | -| **Latin** | *Scientia valoris* | Science of value | -| **German** | *Axiologie* / *Wertlehre* | Value-theory | -| **French** | *Axiologie* / *Théorie de la valeur* | Value-theory | -| **Russian** | Аксиология (*Aksiologiya*) | Axiology | -| **Japanese** | 価値論 (*Kachironnot*) | Value-theory | -| **Chinese** | 价值论 (*Jiàzhílùn*) | Value-theory | -| **Arabic** | علم القيم (*'Ilm al-Qiyam*) | Science of values | -| **Sanskrit** | मूल्य-विज्ञान (*Mūlya-vijñāna*) | Value-knowledge | - ---- - -## Historical Development - -### Ancient Antecedents (Before "Axiology") - -#### Greek Philosophy (5th-3rd century BCE) - -**Socrates** (470-399 BCE): -- Questioned conventional values ("What is the good?") -- Introduced value-inquiry as central to philosophy -- *"The unexamined life is not worth living"* - value of self-knowledge - -**Plato** (428-348 BCE): -- *Theory of Forms*: Absolute values (Good, Beautiful, Just) exist independently -- *Republic*: Hierarchy of values (wisdom > courage > temperance > justice) -- *Form of the Good* - ultimate value, source of all other values - -**Aristotle** (384-322 BCE): -- *Nicomachean Ethics*: Virtue as excellence (*aretē*) -- **Intrinsic vs. Instrumental Value**: Distinction between ends and means -- *Eudaimonia* (flourishing) as highest human value - -#### Medieval Philosophy (4th-14th century CE) - -**Augustine of Hippo** (354-430 CE): -- Christian values hierarchy: God (highest) → soul → body → material goods -- *De Doctrina Christiana*: Things to be "used" (*uti*) vs. "enjoyed" (*frui*) - -**Thomas Aquinas** (1225-1274): -- Natural Law theory: Universal values grounded in human nature -- Hierarchy of goods: Divine → intellectual → physical - -#### Early Modern (16th-18th century) - -**David Hume** (1711-1776): -- Is-Ought Problem: Can't derive value judgments from factual statements -- Sentiment theory of value: Values grounded in human sentiments - -**Immanuel Kant** (1724-1804): -- **Categorical Imperative**: Persons have absolute value (ends-in-themselves) -- Moral worth independent of consequences -- Foundation for deontological ethics - ---- - -### Formal Axiology (1900-Present) - -#### Founding Era (1900-1920) - -**Eduard von Hartmann** (1842-1906): -- *Grundriss der Axiologie* (1909) -- Systematized value theory as distinct philosophical discipline - -**Paul Lapie** (1869-1927): -- *Logique de la volonté* (1902) -- Coined "axiologie" independently - -**Alexius Meinong** (1853-1920): -- *Zur Grundlegung der allgemeinen Werttheorie* (1923) -- Value as objective property of objects -- Value-feelings (*Wertgefühle*) vs. value-properties - -#### Phenomenological Axiology (1913-1928) - -**Max Scheler** (1874-1928): -- *Der Formalismus in der Ethik* (1913-1916) -- Values as *a priori* intuited essences -- **Hierarchy of Values** (low → high): - 1. Pleasant/unpleasant (sensory) - 2. Noble/vulgar (vital) - 3. Spiritual values (intellectual, aesthetic, legal) - 4. Holy/unholy (religious) -- Values known through emotional intuition (*Wertfühlen*) - -**Nicolai Hartmann** (1882-1950): -- *Ethik* (1926) -- Objective value realism: Values exist independently of subjects -- Strength vs. Height: Strong values (e.g., justice) vs. high values (e.g., love) - -#### Formal Axiology (1967-Present) - -**Robert S. Hartman** (1910-1973): -- *The Structure of Value* (1967) -- **Mathematical axiology**: Value as degree of concept-fulfillment -- Three dimensions of value: - 1. **Systemic** (*S*): Conceptual perfection (mathematics, logic) - 2. **Extrinsic** (*E*): Practical utility (tools, instruments) - 3. **Intrinsic** (*I*): Unique worth (persons, art, experiences) -- Axiomatic value theory (18 axioms) - ---- - -## Contemporary Schools - -### Value Realism - -**Position**: Values exist objectively, independent of human minds - -**Representatives**: -- **G.E. Moore** (1873-1958): "Good" as non-natural property -- **Nicolai Hartmann**: Values as ideal essences -- **David Brink**: Moral realism, values as objective features - -**Arguments**: -- Convergence: Cultures converge on basic values (e.g., harm is bad) -- Moral phenomenology: Values *seem* objective -- Best explanation: Objectivity explains disagreement (we're all trying to discover truth) - -### Value Subjectivism - -**Position**: Values are projections of human preferences/emotions - -**Representatives**: -- **David Hume**: Sentimentalism -- **A.J. Ayer**: Emotivism - value statements are expressions of emotion -- **Simon Blackburn**: Quasi-realism - -**Arguments**: -- Metaphysical parsimony: No need for strange "value properties" -- Diversity: Radical value disagreements across cultures -- Motivation: Values necessarily motivate → must be grounded in desires - -### Value Constructivism - -**Position**: Values are constructed through social/rational procedures - -**Representatives**: -- **John Rawls**: Justice as fair agreement behind "veil of ignorance" -- **Christine Korsgaard**: Kantian constructivism -- **Jürgen Habermas**: Discourse ethics - -**Arguments**: -- Objectivity without metaphysics: Intersubjective agreement -- Respect for autonomy: Values we give ourselves -- Democratic legitimacy: Values emerge from dialogue - ---- - -## Axiology in Economics - -### Classical Economics (18th-19th century) - -**Adam Smith** (1723-1790): -- *The Wealth of Nations* (1776) -- **Diamond-Water Paradox**: Diamonds (less useful) more valuable than water -- Use-value vs. exchange-value distinction - -**David Ricardo** (1772-1823): -- Labor theory of value: Value derives from labor input - -**Karl Marx** (1818-1883): -- *Das Kapital* (1867) -- Exchange-value vs. use-value -- Critique: Capitalism treats labor as commodity - -### Marginalist Revolution (1870s) - -**William Stanley Jevons**, **Carl Menger**, **Léon Walras**: -- **Marginal utility theory**: Value = utility of last unit consumed -- Solved diamond-water paradox: Water's marginal utility is low (abundant) - -### Welfare Economics (1900-Present) - -**Vilfredo Pareto** (1848-1923): -- **Pareto efficiency**: No one can be made better off without someone worse off -- Foundation for modern welfare analysis - -**John Hicks** & **Nicholas Kaldor** (1939): -- **Kaldor-Hicks criterion**: Compensation principle for policy evaluation - -**Amartya Sen** (1933-Present): -- Nobel Prize 1998 -- *Collective Choice and Social Welfare* (1970) -- **Capability approach**: Value = capabilities (freedoms) not just utility -- Critique of utilitarianism: Ignores distribution, adaptive preferences - ---- - -## Axiology in Computer Science & AI - -### Decision Theory - -**John von Neumann** & **Oskar Morgenstern** (1944): -- *Theory of Games and Economic Behavior* -- **Expected utility theory**: Rational choice under uncertainty -- Axioms: Completeness, transitivity, continuity, independence - -### Preference Learning - -**Machine learning of value functions**: -- Inverse reinforcement learning (Ng & Russell, 2000) -- Learning from human feedback (RLHF) -- Preference elicitation algorithms - -### AI Alignment & Value Loading - -**Stuart Russell** (2019): -- *Human Compatible: AI and the Problem of Control* -- **Value alignment problem**: How to ensure AI optimizes human values -- Uncertainty about human values → provably beneficial AI - -**Nick Bostrom** (2014): -- *Superintelligence* -- **Instrumental convergence**: AIs converge on instrumental goals regardless of terminal values -- Paperclip maximizer thought experiment - ---- - -## Formal Representations - -### Preference Relations - -Given set $X$ of alternatives, preference relation $\succsim$ ("at least as good as"): - -**Properties**: -- **Completeness**: $\forall x,y \in X: x \succsim y \lor y \succsim x$ -- **Transitivity**: $x \succsim y \land y \succsim z \Rightarrow x \succsim z$ -- **Reflexivity**: $x \succsim x$ - -**Strict preference**: $x \succ y \iff x \succsim y \land \neg(y \succsim x)$ - -**Indifference**: $x \sim y \iff x \succsim y \land y \succsim x$ - -### Utility Functions - -**Representation theorem** (Debreu, 1954): -If $\succsim$ is complete, transitive, continuous, then $\exists$ utility function $u: X \to \mathbb{R}$ such that: - -$$x \succsim y \iff u(x) \geq u(y)$$ - -**Ordinal utility**: Only order matters, not magnitude - -**Cardinal utility**: Magnitude differences are meaningful - -### Social Welfare Functions - -**Aggregation**: $n$ individuals, utilities $u_1, \ldots, u_n$ - -**Utilitarian** (Bentham): -$$W = \sum_{i=1}^n u_i$$ - -**Rawlsian** (maximin): -$$W = \min_i u_i$$ - -**Weighted sum**: -$$W = \sum_{i=1}^n w_i u_i, \quad \sum_i w_i = 1$$ - -**Nash** (product): -$$W = \prod_{i=1}^n u_i$$ - ---- - -## Connections to This Library - -This implementation operationalizes: - -1. **Classical axiology** → Type system (Fairness, Welfare, etc.) -2. **Formal axiology** → Measurable value functions -3. **Welfare economics** → Social welfare functions -4. **AI alignment** → Verification of value satisfaction -5. **Multi-criteria decision** → Pareto frontier analysis - ---- - -## References - -### Primary Sources - -- Aristotle. (350 BCE). *Nicomachean Ethics*. -- Kant, I. (1785). *Groundwork of the Metaphysics of Morals*. -- Scheler, M. (1916). *Formalism in Ethics and Non-Formal Ethics of Values*. -- Hartman, R.S. (1967). *The Structure of Value*. - -### Contemporary - -- Sen, A. (1970). *Collective Choice and Social Welfare*. -- Rawls, J. (1971). *A Theory of Justice*. -- Bostrom, N. (2014). *Superintelligence*. -- Russell, S. (2019). *Human Compatible*. - -### Technical - -- von Neumann, J., & Morgenstern, O. (1944). *Theory of Games and Economic Behavior*. -- Arrow, K. (1951). *Social Choice and Individual Values*. -- Ng, A.Y., & Russell, S. (2000). "Algorithms for Inverse Reinforcement Learning". diff --git a/docs/theory/CROSS_CULTURAL_PERSPECTIVES.adoc b/docs/theory/CROSS_CULTURAL_PERSPECTIVES.adoc new file mode 100644 index 0000000..6503c33 --- /dev/null +++ b/docs/theory/CROSS_CULTURAL_PERSPECTIVES.adoc @@ -0,0 +1,435 @@ +== Cross-Cultural Perspectives on Value Theory + +=== Beyond Western Philosophy + +==== Indian Philosophy + +===== Vedic Period (1500-500 BCE) + +*Ṛta* (ऋत) - Cosmic Order/Truth: - Pre-axial concept of value as cosmic +harmony - Foundation for later dharma concept - Value inherent in +natural order + +*Upanishads* (800-200 BCE): - *Brahman* as ultimate reality and value - +*Ātman* (self) identified with Brahman - Value hierarchy: Knowledge > +ritual > material + +===== Classical Hindu Philosophy + +*Puruṣārthas* (Four Aims of Life): 1. *Dharma* (धर्म) - Righteousness, +moral law 2. *Artha* (अर्थ) - Prosperity, economic value 3. *Kāma* (काम) +- Pleasure, aesthetic/emotional value 4. *Mokṣa* (मोक्ष) - Liberation +(highest value) + +*Bhagavad Gītā* (circa 200 BCE-200 CE): - *Svadharma*: Value relative to +one’s station (_varṇa_) - *Niṣkāma karma*: Action without attachment to +fruits - Three paths (_mārgas_): Knowledge, devotion, action + +===== Buddhist Axiology + +*Four Noble Truths* (Catvāri Ārya Satyāni): 1. _Duḥkha_ - +Suffering/dissatisfaction (disvalue) 2. _Samudaya_ - Origin of suffering +(craving/_tṛṣṇā_) 3. _Nirodha_ - Cessation (value achieved through +elimination) 4. _Mārga_ - Path to cessation + +*Middle Way* (_Madhyamā-Pratipad_): - Rejection of extremes (asceticism +vs. hedonism) - Value as balance, not maximization + +*Dependent Origination* (_Pratītyasamutpāda_): - Values lack inherent +existence - Contextual, relational value theory + +*Mahāyāna*: Bodhisattva ideal - compassion as supreme value + +===== Jain Ethics + +*Ahiṃsā* (अहिंसा) - Non-violence: - Primary value, more extreme than +Hindu/Buddhist - Extends to thoughts, words, deeds + +*Anekāntavāda* - Many-sidedness: - No single perspective captures +complete truth - Value pluralism as metaphysical necessity + +*Syādvāda* - Conditional predication: - Seven-fold judgment +(_Saptabhaṅgī_) - Truth and value are contextual, multi-aspected + +''''' + +==== Chinese Philosophy + +===== Confucianism (儒家) + +*Confucius* (孔子, 551-479 BCE): + +*Five Constants* (_Wǔcháng_ 五常): 1. *Rén* (仁) - Benevolence, humanity +2. *Yì* (义) - Righteousness, justice 3. *Lǐ* (礼) - Ritual propriety, +etiquette 4. *Zhì* (智) - Wisdom, knowledge 5. *Xìn* (信) - Integrity, +trustworthiness + +*Five Relationships* (_Wǔlún_ 五伦): - Ruler-subject, father-son, +husband-wife, elder-younger, friend-friend - Value as relational +harmony, not individual rights + +*Mencius* (孟子, 372-289 BCE): - Human nature is inherently good (_xìng +shàn_ 性善) - Four sprouts: Compassion, shame, courtesy, moral judgment +- Value cultivation through education + +*Xunzi* (荀子, 313-238 BCE): - Human nature is inherently selfish - +Value created through ritual and education - Constructivist axiology + +===== Daoism (道家) + +*Laozi* (老子, 6th century BCE?): + +*Dào* (道) - Way/Path: - Ultimate reality, pre-conceptual - Value in +spontaneity (_zìrán_ 自然 - "`self-so-ness`") - *Wú wéi* (無為) - +Non-action/effortless action + +*Dé* (德) - Virtue/Power: - Not moral virtue, but potency - Alignment +with Dào + +*Value Paradoxes*: - "`The highest good is like water`" (soft > hard) - +"`Know the masculine, keep to the feminine`" - Reversal of conventional +values + +*Zhuangzi* (莊子, 369-286 BCE): - Relativism: "`Is-ness`" (_shì fēi_ +是非) is conventional - Value freedom from fixed values - _Qíwù_ (齊物) +- Equalizing things + +===== Mohism (墨家) + +*Mozi* (墨子, 470-391 BCE): + +*Jiān’ài* (兼愛) - Universal love: - Equal concern for all +(vs. Confucian graded love) - Consequentialist ethics: Value = utility + +*Ten Doctrines*: Anti-war, anti-fate, meritocracy, frugality - Early +utilitarian calculus: "`Benefit all under heaven`" + +===== Legalism (法家) + +*Han Feizi* (韓非子, 280-233 BCE): - Law (_fǎ_ 法) as supreme value - +Reject morality in governance - Value = state power and order + +''''' + +==== Islamic Philosophy + +===== Quranic Axiology + +*Tawḥīd* (توحيد) - Unity of God: - All value derives from divine will - +God as _al-Ḥaqq_ (الحق) - The Truth/Reality + +*Justice* (_’Adl_ عدل): - Central Quranic value - Divine justice as +template for human justice + +*Mercy* (_Raḥma_ رحمة): - "`In the name of God, the Merciful, the +Compassionate`" - Balance with justice + +===== Islamic Philosophy (Falsafa) + +*Al-Farabi* (870-950 CE): - _Al-Madīna al-Fāḍila_ (The Virtuous City) - +Happiness (_sa’āda_) as highest value - Integration of Aristotle with +Islam + +*Ibn Sina (Avicenna)* (980-1037): - Essence-existence distinction - +Necessary Being (God) as source of all value - Neo-Platonic emanationism + +*Al-Ghazali* (1058-1111): - Critique of rationalist ethics - +Occasionalism: God creates anew each moment - Value in divine command, +not reason + +*Ibn Rushd (Averroes)* (1126-1198): - Defended philosophy against +Al-Ghazali - Harmony of reason and revelation - Double truth theory + +===== Sufism + +*Maqāmāt* (Stages) and *Aḥwāl* (States): - Value as spiritual progress - +Love (_'`ishq__) as highest value - Union with God (__fanā`'_) + +*Rumi* (1207-1273): - "`Love is the bridge between you and everything`" +- Value transcends rational calculation + +''''' + +==== African Philosophy + +===== Ubuntu Philosophy (Southern Africa) + +*"`Umuntu ngumuntu ngabantu`"* (Zulu): - "`A person is a person through +other persons`" - Relational ontology → relational axiology - Individual +value inseparable from community + +*Botho/Ubuntu* (Tswana/Zulu): - Compassion, reciprocity, dignity, +harmony - Communitarian ethics vs. Western individualism + +*Restorative Justice*: - Value: Healing relationships > punishment - +Applied in South African Truth & Reconciliation Commission + +===== Ancient Egyptian _Ma’at_ + +*Ma’at* (𓅓𓁐𓏏𓁐): - Truth, justice, cosmic order (1500+ BCE) - Pharaoh’s +role: Maintain ma’at - Heart weighed against feather of ma’at in +afterlife - Precursor to later justice concepts + +===== Yoruba Philosophy (West Africa) + +*Ìwà* - Character/essence: - Central value concept - "`Ìwà l’ẹwà`" - +Character is beauty + +*Àjẹ* - Spiritual/economic power: - Integration of material and +spiritual value - Wealth without character is disvalued + +''''' + +==== Indigenous American Philosophies + +===== Lakota Values + +*Wóčhekiye* - Seven Sacred Rites: - Value in ritual and connection to +land + +*Mitákuye Oyásʼiŋ* - "`All my relations`": - Kinship extends to all +beings - Ecological value theory + +===== Nahua Philosophy (Aztec/Mexica) + +*In Xóchitl In Cuícatl* - "`Flower and song`": - Truth/value expressed +through poetry and art - Aesthetic epistemology + +*Teotl* - Divine energy/power: - Monist ontology → unified value theory +- Balance of opposites + +*Tloque Nahuaque* - "`Lord of the Near and Far`": - Ultimate +value/reality + +''''' + +==== Japanese Philosophy + +===== Shinto + +*Kami* (神) - Sacred spirit/force: - Value in natural phenomena - Purity +(_kiyome_) as value + +*Wa* (和) - Harmony: - Social cohesion as supreme value - Influences +business ethics (_kaizen_, _nemawashi_) + +===== Zen Buddhism + +*Mu* (無) - Emptiness/nothingness: - Value in non-attachment - Direct +experience > conceptual knowledge + +*Wabi-Sabi* (侘寂): - Beauty in imperfection and impermanence - +Aesthetic value theory + +*Bushido* (武士道) - Way of the Warrior: - Honor, loyalty, +self-discipline - Death over dishonor + +''''' + +=== Heterodox Western Traditions + +==== Austrian School Economics + +*Carl Menger* (1840-1921): - *Subjective theory of value*: Value is not +intrinsic but subjective - Marginal utility: Value of next unit, not +total - Ordinal rankings suffice (no cardinal utility needed) + +*Ludwig von Mises* (1881-1973): - _Human Action_ (1949) - *Praxeology*: +Study of purposeful human action - Value scales: Individuals rank ends +ordinally - Critique of interpersonal utility comparisons (welfare +economics impossible) + +*Friedrich Hayek* (1899-1992): - *Spontaneous order*: Values emerge from +decentralized process - Knowledge problem: Central planning can’t +aggregate dispersed value information - Tradition as repository of +evolved values + +*Murray Rothbard* (1926-1995): - Natural rights axiom: Self-ownership - +Deontological libertarianism - Critique of consequentialist ethics + +''''' + +==== Anarchist Value Theory + +*Pierre-Joseph Proudhon* (1809-1865): - "`Property is theft`" - +Mutualism: Value in reciprocal exchange - Labor theory of value +(pre-Marxist) + +*Peter Kropotkin* (1842-1921): - _Mutual Aid_ (1902) - Cooperation as +evolutionary value - Anarcho-communism: "`From each… to each…`" + +*Emma Goldman* (1869-1940): - Individual autonomy as primary value - +Critique of authority (state, church, patriarchy) + +''''' + +==== Feminist Axiology + +*Carol Gilligan* (1936-Present): - _In a Different Voice_ (1982) - +*Ethics of care* vs. ethics of justice - Relational values, contextual +reasoning + +*Nel Noddings* (1929-Present): - Caring as fundamental value - Receptive +attention to particular others + +*Virginia Held* (1929-Present): - Care ethics as comprehensive moral +theory - Critique of social contract theory’s individualism + +*Audre Lorde* (1934-1992): - "`The master’s tools will never dismantle +the master’s house`" - Value of difference and diversity - +Intersectional analysis + +''''' + +==== Ecological/Deep Ecology + +*Aldo Leopold* (1887-1948): - _A Sand County Almanac_ (1949) - *Land +Ethic*: "`A thing is right when it tends to preserve the integrity, +stability, and beauty of the biotic community`" - Intrinsic value of +ecosystems + +*Arne Næss* (1912-2009): - Deep ecology vs. shallow ecology - +*Self-realization*: Expanded ecological self - Biocentric equality: All +life has equal right to flourish + +*Holmes Rolston III* (1932-Present): - Environmental values: Intrinsic, +instrumental, systemic - Nature creates value (not just humans) + +''''' + +==== Pragmatist Axiology + +*William James* (1842-1910): - Pragmatic theory of truth: Value is +"`cash value`" in experience - Pluralism: No single value system + +*John Dewey* (1859-1952): - _Theory of Valuation_ (1939) - Values as +outcomes of inquiry - Continuity of means and ends + +*Hilary Putnam* (1926-2016): - Fact-value entanglement - "`Thick`" +ethical concepts: Cruel, kind, brave + +''''' + +=== Comparative Analysis + +[width="100%",cols="22%,28%,24%,26%",options="header",] +|=== +|Tradition |Primary Value |Metaphysics |Epistemology +|*Confucian* |Harmony (_hé_) |Relational |Ritual cultivation +|*Daoist* |Spontaneity (_zìrán_) |Monist (Dao) |Non-conceptual knowing +|*Buddhist* |Cessation (_nirodha_) |Emptiness |Meditation +|*Hindu* |Liberation (_mokṣa_) |Brahman |Knowledge (_jñāna_) +|*Islamic* |Divine will (_irāda_) |Theistic |Revelation + reason +|*Ubuntu* |Community (_ubuntu_) |Relational |Communal wisdom +|*Austrian* |Subjective preference |Individualist |Praxeological +|*Feminist* |Care |Relational |Contextual +|*Deep Ecology* |Biocentric equality |Ecological holism |Expanded self +|=== + +''''' + +=== Implications for Axiology.jl + +==== Multi-Cultural Value Systems + +This library can encode diverse value traditions: + +*Confucian Harmony* (五常): + +[source,julia] +---- +harmony = Welfare( + metric = :relational_balance, + components = [:ruler_subject, :father_son, :husband_wife, :elder_younger, :friend_friend] +) +---- + +*Ubuntu Relational Ethics*: + +[source,julia] +---- +ubuntu = Fairness( + metric = :community_welfare, + protected_attributes = [:individual, :community], + threshold = 0.0 # No individual disadvantage acceptable +) +---- + +*Buddhist Middle Way*: + +[source,julia] +---- +middle_way = Efficiency( + metric = :balance, + avoid_extremes = [:asceticism, :hedonism] +) +---- + +*Islamic Justice* (_’Adl_): + +[source,julia] +---- +adl = Fairness( + metric = :divine_justice, + includes_mercy = true +) +---- + +*Deep Ecology Biocentric Equality*: + +[source,julia] +---- +biocentric = Safety( + invariant = "∀ species. equal right to flourish", + scope = :all_life +) +---- + +==== Pluralistic Value Aggregation + +Supporting non-Western value systems requires: 1. *Non-utilitarian +aggregation* (Rawlsian, lexicographic) 2. *Relational values* (not just +individual utility) 3. *Threshold constraints* (deontological) 4. +*Context-sensitivity* (particularist ethics) + +''''' + +=== References + +==== Indian Philosophy + +* Radhakrishnan, S., & Moore, C. (1957). _A Sourcebook in Indian +Philosophy_. +* Hiriyanna, M. (1932). _Outlines of Indian Philosophy_. + +==== Chinese Philosophy + +* Chan, W.-T. (1963). _A Source Book in Chinese Philosophy_. +* Graham, A.C. (1989). _Disputers of the Tao_. + +==== Islamic Philosophy + +* Nasr, S.H., & Leaman, O. (Eds.). (1996). _History of Islamic +Philosophy_. +* Fakhry, M. (2004). _A History of Islamic Philosophy_. + +==== African Philosophy + +* Ramose, M.B. (1999). _African Philosophy Through Ubuntu_. +* Wiredu, K. (1996). _Cultural Universals and Particulars_. + +==== Austrian School + +* Mises, L. von. (1949). _Human Action_. +* Hayek, F.A. (1988). _The Fatal Conceit_. + +==== Feminist Ethics + +* Gilligan, C. (1982). _In a Different Voice_. +* Held, V. (2006). _The Ethics of Care_. + +==== Deep Ecology + +* Næss, A. (1973). "`The Shallow and the Deep, Long-Range Ecology +Movement`". +* Rolston, H. (1988). _Environmental Ethics_. diff --git a/docs/theory/CROSS_CULTURAL_PERSPECTIVES.md b/docs/theory/CROSS_CULTURAL_PERSPECTIVES.md deleted file mode 100644 index aa6884d..0000000 --- a/docs/theory/CROSS_CULTURAL_PERSPECTIVES.md +++ /dev/null @@ -1,485 +0,0 @@ - -# Cross-Cultural Perspectives on Value Theory - -## Beyond Western Philosophy - -### Indian Philosophy - -#### Vedic Period (1500-500 BCE) - -**Ṛta** (ऋत) - Cosmic Order/Truth: -- Pre-axial concept of value as cosmic harmony -- Foundation for later dharma concept -- Value inherent in natural order - -**Upanishads** (800-200 BCE): -- **Brahman** as ultimate reality and value -- **Ātman** (self) identified with Brahman -- Value hierarchy: Knowledge > ritual > material - -#### Classical Hindu Philosophy - -**Puruṣārthas** (Four Aims of Life): -1. **Dharma** (धर्म) - Righteousness, moral law -2. **Artha** (अर्थ) - Prosperity, economic value -3. **Kāma** (काम) - Pleasure, aesthetic/emotional value -4. **Mokṣa** (मोक्ष) - Liberation (highest value) - -**Bhagavad Gītā** (circa 200 BCE-200 CE): -- **Svadharma**: Value relative to one's station (*varṇa*) -- **Niṣkāma karma**: Action without attachment to fruits -- Three paths (*mārgas*): Knowledge, devotion, action - -#### Buddhist Axiology - -**Four Noble Truths** (Catvāri Ārya Satyāni): -1. *Duḥkha* - Suffering/dissatisfaction (disvalue) -2. *Samudaya* - Origin of suffering (craving/*tṛṣṇā*) -3. *Nirodha* - Cessation (value achieved through elimination) -4. *Mārga* - Path to cessation - -**Middle Way** (*Madhyamā-Pratipad*): -- Rejection of extremes (asceticism vs. hedonism) -- Value as balance, not maximization - -**Dependent Origination** (*Pratītyasamutpāda*): -- Values lack inherent existence -- Contextual, relational value theory - -**Mahāyāna**: Bodhisattva ideal - compassion as supreme value - -#### Jain Ethics - -**Ahiṃsā** (अहिंसा) - Non-violence: -- Primary value, more extreme than Hindu/Buddhist -- Extends to thoughts, words, deeds - -**Anekāntavāda** - Many-sidedness: -- No single perspective captures complete truth -- Value pluralism as metaphysical necessity - -**Syādvāda** - Conditional predication: -- Seven-fold judgment (*Saptabhaṅgī*) -- Truth and value are contextual, multi-aspected - ---- - -### Chinese Philosophy - -#### Confucianism (儒家) - -**Confucius** (孔子, 551-479 BCE): - -**Five Constants** (*Wǔcháng* 五常): -1. **Rén** (仁) - Benevolence, humanity -2. **Yì** (义) - Righteousness, justice -3. **Lǐ** (礼) - Ritual propriety, etiquette -4. **Zhì** (智) - Wisdom, knowledge -5. **Xìn** (信) - Integrity, trustworthiness - -**Five Relationships** (*Wǔlún* 五伦): -- Ruler-subject, father-son, husband-wife, elder-younger, friend-friend -- Value as relational harmony, not individual rights - -**Mencius** (孟子, 372-289 BCE): -- Human nature is inherently good (*xìng shàn* 性善) -- Four sprouts: Compassion, shame, courtesy, moral judgment -- Value cultivation through education - -**Xunzi** (荀子, 313-238 BCE): -- Human nature is inherently selfish -- Value created through ritual and education -- Constructivist axiology - -#### Daoism (道家) - -**Laozi** (老子, 6th century BCE?): - -**Dào** (道) - Way/Path: -- Ultimate reality, pre-conceptual -- Value in spontaneity (*zìrán* 自然 - "self-so-ness") -- **Wú wéi** (無為) - Non-action/effortless action - -**Dé** (德) - Virtue/Power: -- Not moral virtue, but potency -- Alignment with Dào - -**Value Paradoxes**: -- "The highest good is like water" (soft > hard) -- "Know the masculine, keep to the feminine" -- Reversal of conventional values - -**Zhuangzi** (莊子, 369-286 BCE): -- Relativism: "Is-ness" (*shì fēi* 是非) is conventional -- Value freedom from fixed values -- *Qíwù* (齊物) - Equalizing things - -#### Mohism (墨家) - -**Mozi** (墨子, 470-391 BCE): - -**Jiān'ài** (兼愛) - Universal love: -- Equal concern for all (vs. Confucian graded love) -- Consequentialist ethics: Value = utility - -**Ten Doctrines**: Anti-war, anti-fate, meritocracy, frugality -- Early utilitarian calculus: "Benefit all under heaven" - -#### Legalism (法家) - -**Han Feizi** (韓非子, 280-233 BCE): -- Law (*fǎ* 法) as supreme value -- Reject morality in governance -- Value = state power and order - ---- - -### Islamic Philosophy - -#### Quranic Axiology - -**Tawḥīd** (توحيد) - Unity of God: -- All value derives from divine will -- God as *al-Ḥaqq* (الحق) - The Truth/Reality - -**Justice** (*'Adl* عدل): -- Central Quranic value -- Divine justice as template for human justice - -**Mercy** (*Raḥma* رحمة): -- "In the name of God, the Merciful, the Compassionate" -- Balance with justice - -#### Islamic Philosophy (Falsafa) - -**Al-Farabi** (870-950 CE): -- *Al-Madīna al-Fāḍila* (The Virtuous City) -- Happiness (*sa'āda*) as highest value -- Integration of Aristotle with Islam - -**Ibn Sina (Avicenna)** (980-1037): -- Essence-existence distinction -- Necessary Being (God) as source of all value -- Neo-Platonic emanationism - -**Al-Ghazali** (1058-1111): -- Critique of rationalist ethics -- Occasionalism: God creates anew each moment -- Value in divine command, not reason - -**Ibn Rushd (Averroes)** (1126-1198): -- Defended philosophy against Al-Ghazali -- Harmony of reason and revelation -- Double truth theory - -#### Sufism - -**Maqāmāt** (Stages) and **Aḥwāl** (States): -- Value as spiritual progress -- Love (*'ishq*) as highest value -- Union with God (*fanā'*) - -**Rumi** (1207-1273): -- "Love is the bridge between you and everything" -- Value transcends rational calculation - ---- - -### African Philosophy - -#### Ubuntu Philosophy (Southern Africa) - -**"Umuntu ngumuntu ngabantu"** (Zulu): -- "A person is a person through other persons" -- Relational ontology → relational axiology -- Individual value inseparable from community - -**Botho/Ubuntu** (Tswana/Zulu): -- Compassion, reciprocity, dignity, harmony -- Communitarian ethics vs. Western individualism - -**Restorative Justice**: -- Value: Healing relationships > punishment -- Applied in South African Truth & Reconciliation Commission - -#### Ancient Egyptian *Ma'at* - -**Ma'at** (𓅓𓁐𓏏𓁐): -- Truth, justice, cosmic order (1500+ BCE) -- Pharaoh's role: Maintain ma'at -- Heart weighed against feather of ma'at in afterlife -- Precursor to later justice concepts - -#### Yoruba Philosophy (West Africa) - -**Ìwà** - Character/essence: -- Central value concept -- "Ìwà l'ẹwà" - Character is beauty - -**Àjẹ** - Spiritual/economic power: -- Integration of material and spiritual value -- Wealth without character is disvalued - ---- - -### Indigenous American Philosophies - -#### Lakota Values - -**Wóčhekiye** - Seven Sacred Rites: -- Value in ritual and connection to land - -**Mitákuye Oyásʼiŋ** - "All my relations": -- Kinship extends to all beings -- Ecological value theory - -#### Nahua Philosophy (Aztec/Mexica) - -**In Xóchitl In Cuícatl** - "Flower and song": -- Truth/value expressed through poetry and art -- Aesthetic epistemology - -**Teotl** - Divine energy/power: -- Monist ontology → unified value theory -- Balance of opposites - -**Tloque Nahuaque** - "Lord of the Near and Far": -- Ultimate value/reality - ---- - -### Japanese Philosophy - -#### Shinto - -**Kami** (神) - Sacred spirit/force: -- Value in natural phenomena -- Purity (*kiyome*) as value - -**Wa** (和) - Harmony: -- Social cohesion as supreme value -- Influences business ethics (*kaizen*, *nemawashi*) - -#### Zen Buddhism - -**Mu** (無) - Emptiness/nothingness: -- Value in non-attachment -- Direct experience > conceptual knowledge - -**Wabi-Sabi** (侘寂): -- Beauty in imperfection and impermanence -- Aesthetic value theory - -**Bushido** (武士道) - Way of the Warrior: -- Honor, loyalty, self-discipline -- Death over dishonor - ---- - -## Heterodox Western Traditions - -### Austrian School Economics - -**Carl Menger** (1840-1921): -- **Subjective theory of value**: Value is not intrinsic but subjective -- Marginal utility: Value of next unit, not total -- Ordinal rankings suffice (no cardinal utility needed) - -**Ludwig von Mises** (1881-1973): -- *Human Action* (1949) -- **Praxeology**: Study of purposeful human action -- Value scales: Individuals rank ends ordinally -- Critique of interpersonal utility comparisons (welfare economics impossible) - -**Friedrich Hayek** (1899-1992): -- **Spontaneous order**: Values emerge from decentralized process -- Knowledge problem: Central planning can't aggregate dispersed value information -- Tradition as repository of evolved values - -**Murray Rothbard** (1926-1995): -- Natural rights axiom: Self-ownership -- Deontological libertarianism -- Critique of consequentialist ethics - ---- - -### Anarchist Value Theory - -**Pierre-Joseph Proudhon** (1809-1865): -- "Property is theft" -- Mutualism: Value in reciprocal exchange -- Labor theory of value (pre-Marxist) - -**Peter Kropotkin** (1842-1921): -- *Mutual Aid* (1902) -- Cooperation as evolutionary value -- Anarcho-communism: "From each... to each..." - -**Emma Goldman** (1869-1940): -- Individual autonomy as primary value -- Critique of authority (state, church, patriarchy) - ---- - -### Feminist Axiology - -**Carol Gilligan** (1936-Present): -- *In a Different Voice* (1982) -- **Ethics of care** vs. ethics of justice -- Relational values, contextual reasoning - -**Nel Noddings** (1929-Present): -- Caring as fundamental value -- Receptive attention to particular others - -**Virginia Held** (1929-Present): -- Care ethics as comprehensive moral theory -- Critique of social contract theory's individualism - -**Audre Lorde** (1934-1992): -- "The master's tools will never dismantle the master's house" -- Value of difference and diversity -- Intersectional analysis - ---- - -### Ecological/Deep Ecology - -**Aldo Leopold** (1887-1948): -- *A Sand County Almanac* (1949) -- **Land Ethic**: "A thing is right when it tends to preserve the integrity, stability, and beauty of the biotic community" -- Intrinsic value of ecosystems - -**Arne Næss** (1912-2009): -- Deep ecology vs. shallow ecology -- **Self-realization**: Expanded ecological self -- Biocentric equality: All life has equal right to flourish - -**Holmes Rolston III** (1932-Present): -- Environmental values: Intrinsic, instrumental, systemic -- Nature creates value (not just humans) - ---- - -### Pragmatist Axiology - -**William James** (1842-1910): -- Pragmatic theory of truth: Value is "cash value" in experience -- Pluralism: No single value system - -**John Dewey** (1859-1952): -- *Theory of Valuation* (1939) -- Values as outcomes of inquiry -- Continuity of means and ends - -**Hilary Putnam** (1926-2016): -- Fact-value entanglement -- "Thick" ethical concepts: Cruel, kind, brave - ---- - -## Comparative Analysis - -| Tradition | Primary Value | Metaphysics | Epistemology | -|-----------|---------------|-------------|--------------| -| **Confucian** | Harmony (*hé*) | Relational | Ritual cultivation | -| **Daoist** | Spontaneity (*zìrán*) | Monist (Dao) | Non-conceptual knowing | -| **Buddhist** | Cessation (*nirodha*) | Emptiness | Meditation | -| **Hindu** | Liberation (*mokṣa*) | Brahman | Knowledge (*jñāna*) | -| **Islamic** | Divine will (*irāda*) | Theistic | Revelation + reason | -| **Ubuntu** | Community (*ubuntu*) | Relational | Communal wisdom | -| **Austrian** | Subjective preference | Individualist | Praxeological | -| **Feminist** | Care | Relational | Contextual | -| **Deep Ecology** | Biocentric equality | Ecological holism | Expanded self | - ---- - -## Implications for Axiology.jl - -### Multi-Cultural Value Systems - -This library can encode diverse value traditions: - -**Confucian Harmony** (五常): -```julia -harmony = Welfare( - metric = :relational_balance, - components = [:ruler_subject, :father_son, :husband_wife, :elder_younger, :friend_friend] -) -``` - -**Ubuntu Relational Ethics**: -```julia -ubuntu = Fairness( - metric = :community_welfare, - protected_attributes = [:individual, :community], - threshold = 0.0 # No individual disadvantage acceptable -) -``` - -**Buddhist Middle Way**: -```julia -middle_way = Efficiency( - metric = :balance, - avoid_extremes = [:asceticism, :hedonism] -) -``` - -**Islamic Justice** (*'Adl*): -```julia -adl = Fairness( - metric = :divine_justice, - includes_mercy = true -) -``` - -**Deep Ecology Biocentric Equality**: -```julia -biocentric = Safety( - invariant = "∀ species. equal right to flourish", - scope = :all_life -) -``` - -### Pluralistic Value Aggregation - -Supporting non-Western value systems requires: -1. **Non-utilitarian aggregation** (Rawlsian, lexicographic) -2. **Relational values** (not just individual utility) -3. **Threshold constraints** (deontological) -4. **Context-sensitivity** (particularist ethics) - ---- - -## References - -### Indian Philosophy -- Radhakrishnan, S., & Moore, C. (1957). *A Sourcebook in Indian Philosophy*. -- Hiriyanna, M. (1932). *Outlines of Indian Philosophy*. - -### Chinese Philosophy -- Chan, W.-T. (1963). *A Source Book in Chinese Philosophy*. -- Graham, A.C. (1989). *Disputers of the Tao*. - -### Islamic Philosophy -- Nasr, S.H., & Leaman, O. (Eds.). (1996). *History of Islamic Philosophy*. -- Fakhry, M. (2004). *A History of Islamic Philosophy*. - -### African Philosophy -- Ramose, M.B. (1999). *African Philosophy Through Ubuntu*. -- Wiredu, K. (1996). *Cultural Universals and Particulars*. - -### Austrian School -- Mises, L. von. (1949). *Human Action*. -- Hayek, F.A. (1988). *The Fatal Conceit*. - -### Feminist Ethics -- Gilligan, C. (1982). *In a Different Voice*. -- Held, V. (2006). *The Ethics of Care*. - -### Deep Ecology -- Næss, A. (1973). "The Shallow and the Deep, Long-Range Ecology Movement". -- Rolston, H. (1988). *Environmental Ethics*. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..721a284 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — Axiology.jl (Developer) + +=== What is Axiology.jl? + +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 eaa9519..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — Axiology.jl (Developer) - -## What is Axiology.jl? -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..0e61593 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — Axiology.jl (User) + +=== What is Axiology.jl? + +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 8b603e1..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — Axiology.jl (User) - -## What is Axiology.jl? -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