Skip to content

docs: Expand EQBSL Rust crate README and update root README with crate details#18

Merged
Steake merged 8 commits intoimplement-rust-crate-version-of-eqbsl-library-with-docs-examples-and-tests-Wn9PR9JC77fhfrom
copilot/sub-pr-17
Mar 13, 2026
Merged

docs: Expand EQBSL Rust crate README and update root README with crate details#18
Steake merged 8 commits intoimplement-rust-crate-version-of-eqbsl-library-with-docs-examples-and-tests-Wn9PR9JC77fhfrom
copilot/sub-pr-17

Conversation

Copy link
Contributor

Copilot AI commented Feb 25, 2026

Expands the Rust crate documentation and updates the project root README to surface the Rust crate alongside the Angular web app.

Changes to rust/README.md

  • Added architecture diagrams using Mermaid (evidence-to-trust pipeline, transitive trust, opinion fusion) with theme-safe styling (color:#000000 on all styled nodes, subgraph fills removed)
  • Added four real-world example implementations with visual diagrams and runnable code: supply chain provenance, DAO reputation-weighted voting, AI agent swarm trust, and P2P lending
  • Expanded API reference with function signatures, parameter tables, and pipeline function descriptions
  • Added feature comparison table vs. traditional trust systems (scalar scores, Web-of-Trust)
  • Corrected EQBSL full name to "Evidence-Qualified Subjective Logic" throughout
  • Fixed diagram/code value mismatches (DAO evidence counts, Agent-3 disbelief label)
  • Fixed let (r, s) = propagated[...] to compile-correct let &(r, s) = propagated.get(...).unwrap()
  • Added missing params.validate() call in supply chain example
  • Corrected calculate_opinion API doc wording (no default parameter)
  • Fixed misleading "Proposal PASSED/REJECTED" output to clearly report DAO collective reputation
  • Fixed Hyperedge comment to match actual node list (agents 2 and 3, not 2/3/4)
  • Fixed Sybil resistance table row to "Partial† (via uncertainty)" with accurate footnote per docs/EQBSL-Primer.md
  • Spelling consistency: anonymisedanonymized, modellingmodeling

Changes to root README.md

  • Added new 🦀 Rust Crate section with feature highlights, Cargo.toml install snippet, quick-start code, and link to rust/README.md
  • Updated project structure tree to include the rust/ directory and its sub-structure
  • Added the Rust crate as the first entry in the ecosystem table
  • Corrected EQBSL terminology ("Evidence-Qualified Subjective Logic") in two places

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

@superconductor-for-github
Copy link

Superconductor is workingView implementation


I'll get back to you soon!

Co-authored-by: Steake <530040+Steake@users.noreply.github.com>
Copilot AI changed the title [WIP] Add Rust crate version of EQBSL library with documentation and tests docs(rust): Expand README with mermaid diagrams and real-world examples Feb 25, 2026
Copilot AI requested a review from Steake February 25, 2026 01:29
@Steake
Copy link
Owner

Steake commented Feb 25, 2026

@copilot Please resolve the issue with the styling of the mermaid diagrams, where background colours mask the text colours. This leads to almost unreadable diagrams.

Co-authored-by: Steake <530040+Steake@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Feb 25, 2026

@copilot Please resolve the issue with the styling of the mermaid diagrams, where background colours mask the text colours. This leads to almost unreadable diagrams.

Fixed in commit c57e95a. Two changes were made to all five diagrams:

  1. Pipeline diagram subgraph fills removed — the fill property was stripped from all six subgraph style directives (only the coloured stroke border is kept). Subgraph fills are the primary source of the masking issue because Mermaid's theme can set white text against the light pastel backgrounds in dark mode.

  2. All node-level styles now include color:#000000 — every style NodeX fill:...,stroke:... in the transitive trust, fusion, DAO voting, and AI swarm diagrams now explicitly pins the text to black, ensuring contrast regardless of GitHub's light/dark theme.

@Steake Steake marked this pull request as ready for review February 25, 2026 03:34
Copilot AI review requested due to automatic review settings February 25, 2026 03:34
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR significantly expands the Rust crate README with comprehensive documentation including architecture diagrams, real-world examples, and detailed API reference. The documentation transforms a basic README into a thorough guide with four practical examples (supply chain, DAO voting, AI agent swarm, and P2P lending) and enhanced Mermaid diagrams that are compatible with both light and dark GitHub themes.

Changes:

  • Added detailed architecture diagrams using Mermaid (evidence-to-trust pipeline, transitive trust, opinion fusion)
  • Included four real-world example implementations with both code and visual diagrams
  • Expanded API documentation with detailed function references and parameter explanations
  • Added comparison table contrasting EQBSL with traditional trust systems
  • Fixed Mermaid diagram styling to ensure text readability in both light and dark themes

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

rust/README.md Outdated
Comment on lines +320 to +351
A["Alice\n b=0.91, u=0.09\n (veteran, high trust)"]
B["Bob\n b=0.62, u=0.38\n (active, moderate trust)"]
C["Carol\n b=0.17, u=0.83\n (new member, high uncertainty)"]
end

subgraph Proposal["Proposal: Upgrade Protocol"]
V["Reputation-Weighted Vote\n weight = b × (1 - u)"]
end

A -->|"weight = 0.82"| V
B -->|"weight = 0.38"| V
C -->|"weight = 0.03"| V

V --> R["Result: Passed\n Weighted majority: 0.74"]

style A fill:#d4edda,stroke:#28a745,color:#000000
style C fill:#fff3cd,stroke:#ffc107,color:#000000
style R fill:#d1ecf1,stroke:#17a2b8,color:#000000
```

```rust
use eqbsl::*;

struct Member { name: String, opinion: Opinion }

fn dao_voting_example() {
// Opinions derived from on-chain interaction history
let members = vec![
Member { name: "alice".into(), opinion: calculate_opinion(100.0, 5.0, 2.0, 0.5) },
Member { name: "bob".into(), opinion: calculate_opinion(30.0, 3.0, 2.0, 0.5) },
Member { name: "carol".into(), opinion: calculate_opinion(2.0, 0.0, 2.0, 0.5) },
];
Copy link

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The opinion values shown in the Mermaid diagram (lines 320-322) don't match the values that would be calculated by the code (lines 347-351).

Diagram shows:

  • Alice: b=0.91, u=0.09
  • Bob: b=0.62, u=0.38
  • Carol: b=0.17, u=0.83

But the code calculates:

  • Alice (100, 5): b=100/107=0.935, u=2/107=0.019
  • Bob (30, 3): b=30/35=0.857, u=2/35=0.057
  • Carol (2, 0): b=2/4=0.5, u=2/4=0.5

Either update the diagram to match the actual calculation results, or adjust the evidence counts in the code to produce the diagram values. For example, to get the diagram values approximately:

  • Alice (10, 1): b≈0.833, u≈0.167 (closer to 0.91, 0.09 would need r≈10, s≈0)
  • Bob (5, 3): b≈0.5, u≈0.2
  • Carol (1, 4): b≈0.143, u≈0.286

Copilot uses AI. Check for mistakes.

// Coordinator's evidence about peers
state.edges.insert(("coord".into(), "agent_2".into()), array![12.0, 8.0, 10.0]);
state.edges.insert(("coord".into(), "agent_3".into()), array![2.0, 9.0, 1.0]);
Copy link

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The disbelief value shown in the diagram for Agent-3 (d=0.61) doesn't match the calculation from the evidence counts r=2, s=8.

With r=2, s=8, k=2:
d = 8/(2+8+2) = 8/12 = 0.667 ≈ 0.67

To get d≈0.61, you would need different evidence counts, such as r=1.5, s=6.5, or similar. Either update the diagram to show d=0.67 or adjust the evidence counts in line 426 to match the diagram value.

Suggested change
state.edges.insert(("coord".into(), "agent_3".into()), array![2.0, 9.0, 1.0]);
state.edges.insert(("coord".into(), "agent_3".into()), array![3.0, 8.0, 1.0]);

Copilot uses AI. Check for mistakes.
rust/README.md Outdated

let mut state = State::new(100); // t=100 (current step)

// Coordinator's evidence about peers
Copy link

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The diagram shows simplified scalar evidence counts (r=12, s=1 for agent_2) while the code uses 3-dimensional evidence vectors with weighted aggregation. This creates a confusing mismatch between what's visualized and what the code actually computes.

For example, the diagram shows agent_2 with r=12, s=1 → b=0.80, but the code uses array![12.0, 8.0, 10.0] which with the given weights produces r≈10.8, s≈11.2 → b≈0.45.

Consider either:

  1. Updating the diagram to note that values are "conceptual/simplified" and don't reflect the actual multi-channel computation
  2. Simplifying the code to use scalar evidence that matches the diagram for clarity
  3. Adding a note explaining the difference between the visualization and implementation
Suggested change
// Coordinator's evidence about peers
// Coordinator's evidence about peers.
// NOTE: These are 3-channel evidence vectors. The high-level diagram in the docs
// uses simplified scalar r,s counts for illustration, so the numeric values differ.

Copilot uses AI. Check for mistakes.
rust/README.md Outdated
let mut h = std::collections::HashMap::new();
h.insert("agent_2".to_string(), "executor".to_string());
h.insert("agent_3".to_string(), "executor".to_string());
state.hypers.insert("task_42".into(), eqbsl::model::Hyperedge {
Copy link

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code uses eqbsl::model::Hyperedge as a fully qualified path despite having use eqbsl::*; at the top of the example, which already brings Hyperedge into scope via the re-export in lib.rs.

For consistency with the rest of the example code, this should be simplified to just Hyperedge. The current approach works but is unnecessarily verbose.

Suggested change
state.hypers.insert("task_42".into(), eqbsl::model::Hyperedge {
state.hypers.insert("task_42".into(), Hyperedge {

Copilot uses AI. Check for mistakes.
rust/README.md Outdated
Comment on lines +369 to +372
let consensus = members.iter().skip(1).fold(members[0].opinion, |acc, m| acc.fuse(&m.opinion));
println!("Consensus opinion: b={:.3}, u={:.3}, E={:.3}",
consensus.b, consensus.u, consensus.expectation());
println!("Proposal {}", if consensus.expectation() > 0.6 { "PASSED" } else { "REJECTED" });
Copy link

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The fusion operation on line 369 computes the consensus of member reputation opinions, but it's not entirely clear what this represents in the context of voting. The weight calculation (lines 354-356) already uses individual opinions, so the fusion result doesn't appear to be used for the voting decision.

Consider clarifying the purpose of the consensus calculation - is it meant to represent the collective reputation of the DAO, or should it be used differently in the voting logic? The current code calculates it but only uses it for display, which might confuse readers about its purpose in the voting mechanism.

Copilot uses AI. Check for mistakes.
rust/README.md Outdated
Comment on lines +554 to +556
| Sybil resistance | KYC | Introducer trust | **Epistemic uncertainty** |
| Serializable / portable | Partial | ✗ | **✓ Full serde support** |

Copy link

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The comparison table claims EQBSL provides "Epistemic uncertainty" as a form of Sybil resistance, but according to the technical documentation (docs/EQBSL-Primer.md:277), "EQBSL does not provide sybil-resistance; it only provides trust computation over events."

While EQBSL can model uncertainty about new/unknown entities, this is not the same as providing Sybil resistance (preventing an attacker from gaining undue influence by creating multiple identities). The table entry is misleading.

Consider either:

  1. Changing the entry to "✗" or "Partial" to be more accurate
  2. Clarifying that uncertainty modeling helps but doesn't constitute true Sybil resistance
  3. Adding a footnote explaining the distinction
Suggested change
| Sybil resistance | KYC | Introducer trust | **Epistemic uncertainty** |
| Serializable / portable | Partial || **✓ Full serde support** |
| Sybil resistance | KYC | Introducer trust | **Partial† (via uncertainty)** |
| Serializable / portable | Partial || **✓ Full serde support** |
† EQBSL itself does not provide Sybil resistance; it only computes trust (opinions) over events. Its explicit modelling of epistemic uncertainty about new or unknown identities can help downstream protocols implement Sybil-resistance policies, but it is not a Sybil-resistance mechanism on its own.

Copilot uses AI. Check for mistakes.
rust/README.md Outdated
Comment on lines +482 to +483
P->>L1: Publish anonymised opinion commitment
P->>L2: Publish anonymised opinion commitment
Copy link

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The document uses British English spelling ("anonymised" on lines 482-483, "modelling" on line 549) while the main repository README uses American English spelling ("modeling"). For consistency with the broader codebase, consider using American English spellings: "anonymized" and "modeling".

Suggested change
P->>L1: Publish anonymised opinion commitment
P->>L2: Publish anonymised opinion commitment
P->>L1: Publish anonymized opinion commitment
P->>L2: Publish anonymized opinion commitment

Copilot uses AI. Check for mistakes.
rust/README.md Outdated
| Feature | Traditional Score | Web-of-Trust | EQBSL |
|:--------|:-----------------|:-------------|:------|
| Representation | Scalar (e.g., 4.2 ★) | Boolean | **Tuple (b, d, u, a)** |
| Uncertainty modelling | ✗ | ✗ | **✓ Explicit via `u`** |
Copy link

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The document uses British English spelling "modelling" while the main repository README uses American English "modeling". For consistency with the broader codebase, consider using the American spelling "modeling".

Suggested change
| Uncertainty modelling ||| **✓ Explicit via `u`** |
| Uncertainty modeling ||| **✓ Explicit via `u`** |

Copilot uses AI. Check for mistakes.
@Steake
Copy link
Owner

Steake commented Feb 25, 2026

@copilot apply changes based on the comments in this thread

…ents

Co-authored-by: Steake <530040+Steake@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Feb 25, 2026

@copilot apply changes based on the comments in this thread

All review comments addressed in commit 883d409:

  • DAO diagram/code mismatch — evidence counts updated to (20,0), (5,1), (1,0) for Alice, Bob, Carol; diagram labels now exactly match calculate_opinion output (b=0.91/0.62/0.33, u=0.09/0.25/0.67, weights 0.83/0.47/0.11); removed ambiguous "Weighted majority" figure
  • DAO consensus comment — added explanation that the fused opinion represents the DAO's collective reputation as seen by an outside observer, not the vote outcome
  • Agent-3 disbelief — diagram label corrected to d=0.67 (= 8/(2+8+2))
  • AI Swarm diagram/code mismatch — added comment in code block noting the diagram uses simplified scalar r,s counts for illustration while the code uses weighted 3-channel vectors
  • eqbsl::model::Hyperedge — simplified to Hyperedge (available via pub use model::*)
  • Sybil resistance row — updated to Partial† (via uncertainty) with a footnote stating EQBSL computes trust over events and does not itself provide Sybil resistance, per docs/EQBSL-Primer.md:277
  • Spellinganonymisedanonymized, modellingmodeling

Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@Steake
Copy link
Owner

Steake commented Mar 10, 2026

@copilot just FYI please make sure we're consistently using the correct terms - it's "Evidence-Qualified Subjective Logic"

…Logic

Co-authored-by: Steake <530040+Steake@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Mar 10, 2026

@copilot just FYI please make sure we're consistently using the correct terms - it's "Evidence-Qualified Subjective Logic"

Fixed in commit 959854f — the rust/README.md introduction now reads "Evidence-Qualified Subjective Logic (EQBSL)". The sub-module heading "Evidence-Based Subjective Logic (EBSL)" for the ebsl module is kept as-is since that's a distinct, correctly-named component.

@Steake
Copy link
Owner

Steake commented Mar 13, 2026

@copilot Merge this

Copy link
Contributor Author

Copilot AI commented Mar 13, 2026

@copilot Merge this

Merging PRs is outside what I'm able to do — I can only push code changes. You'll need to merge this PR directly on GitHub using the "Merge pull request" button.

Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 5 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines +438 to +440
state.hypers.insert("task_42".into(), Hyperedge {
hid: "task_42".into(),
nodes: vec!["agent_2".into(), "agent_3".into()],
rust/README.md Outdated
let consensus = members.iter().skip(1).fold(members[0].opinion, |acc, m| acc.fuse(&m.opinion));
println!("Consensus opinion: b={:.3}, u={:.3}, E={:.3}",
consensus.b, consensus.u, consensus.expectation());
println!("Proposal {}", if consensus.expectation() > 0.6 { "PASSED" } else { "REJECTED" });
rust/README.md Outdated

### `calculate_opinion(r, s, k, a) -> Opinion`

Maps raw evidence counts to an opinion. Uses `K = DEFAULT_K = 2.0` by default.
damping_lambda: 0.7,
witness_top_k: 5,
};

rust/README.md Outdated
// Transitive trust: manufacturer → retailer via distributor
let nodes = vec!["manufacturer".to_string(), "distributor".to_string(), "retailer".to_string()];
let propagated = depth1_propagation_rs(&nodes, &opinions, &state.edges, &params);
let (r, s) = propagated[&("manufacturer".into(), "retailer".into())];
@Steake
Copy link
Owner

Steake commented Mar 13, 2026

@copilot apply changes based on the comments in this thread

Co-authored-by: Steake <530040+Steake@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Mar 13, 2026

@copilot apply changes based on the comments in this thread

All five review comments addressed in commit 8aae3e0:

  • calculate_opinion doc — removed the misleading "by default" wording; now says "Pass DEFAULT_K (= 2.0) for the standard EBSL prior weight"
  • Missing params.validate() — added params.validate().expect("Invalid params") to the supply chain example, consistent with the API reference and basic_usage example
  • propagated[...] won't compile — changed to let &(r, s) = propagated.get(&(...)).unwrap() (correct destructure of the &(f64, f64) reference returned by HashMap::get)
  • Misleading "Proposal PASSED/REJECTED" — replaced with println!("DAO collective reputation: ...") so it clearly reports the group reputation state, not a vote outcome
  • Hyperedge comment/nodes mismatch — comment updated from "agents 2, 3, 4 collaborated" to "agents 2 and 3", matching the actual nodes list in the Hyperedge

@Steake
Copy link
Owner

Steake commented Mar 13, 2026

@copilot OK now update project root README to include the rust crate details too

Co-authored-by: Steake <530040+Steake@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Mar 13, 2026

@copilot OK now update project root README to include the rust crate details too

Done in commit b3ca5de. The root README.md now includes:

  • New 🦀 Rust Crate section (between "Documentation" links and "Technology Stack") with feature highlights, Cargo.toml install snippet, quick-start code, and a link to rust/README.md for full docs and real-world examples
  • Updated project structure treerust/ directory and its sub-structure now appear at the top of the tree
  • Updated ecosystem table — the rust/ crate is listed as the first entry
  • Terminology fix — both occurrences of "Evidence-based Quantum-resistant Belief State Logic" updated to "Evidence-Qualified Subjective Logic"

Copilot AI changed the title docs(rust): Expand README with mermaid diagrams and real-world examples docs: Expand EQBSL Rust crate README and update root README with crate details Mar 13, 2026
@Steake Steake merged commit 3c1036b into implement-rust-crate-version-of-eqbsl-library-with-docs-examples-and-tests-Wn9PR9JC77fh Mar 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants