From f0769746c2002266e15f85b23481c31356967152 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 5 Oct 2026 22:15:12 +0000 Subject: [PATCH 01/10] Add roadmap for the Trust Graph CLI New doc/plan/README.md with a TL;DR, design principles, target workspace architecture, phased roadmap with acceptance criteria, open decisions, and a mapping of the 2022 TODO list onto the phases. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UdKneRqUnsbv1t7NyvcT68 --- doc/plan/README.md | 218 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 doc/plan/README.md diff --git a/doc/plan/README.md b/doc/plan/README.md new file mode 100644 index 0000000..f8d1d05 --- /dev/null +++ b/doc/plan/README.md @@ -0,0 +1,218 @@ +# Trust Graph CLI — Roadmap + +## TL;DR + +**Goal:** turn this repo from a "hello world" scaffold into `trust`, the CLI and +Rust library that every other Trust Graph / Trustcraft component builds on. + +**The plan, in order:** + +1. **Foundation** (separate PR, ready): clap 4, edition 2024, lib + bin split, + 19 tests, CI on Linux/macOS/Windows, Dependabot. +2. **Core data model**: a `trustgraph-core` library crate with a typed, + validated `TrustAtom` (`source`, `target`, `content`, `value`, `timestamp`, + `extra`), canonical JSON, and content-addressed IDs. +3. **Identity & signing**: `did:key` Ed25519 identities, a local keystore, + and signed claims as W3C Verifiable Credentials 2.0 (`eddsa-jcs-2022`). +4. **Real commands**: rename the binary to `trust`; `trust key`, `trust atom + create`, `trust verify`, `trust convert`. JSON on stdout so commands pipe. +5. **Storage**: a pluggable `Store` trait; local file store first, then a + Holochain adapter that speaks the existing `trustgraph-holochain` link-tag + format. +6. **Graph queries**: `trust query` and `trust map` (transitive trust with + depth limits and topic filters). +7. **Release**: tagged releases with prebuilt binaries, crates.io, Homebrew. + +**Decisions I need from you** (details in [Open decisions](#open-decisions)): + +- **License**: this repo has none; the other `trustgraph` repos use Apache-2.0. Use that here too? +- **Value range**: the protocol README says `0..1`; `trustgraph-holochain` allows + `-0.999999999..0.999999999` (negative trust). Which is canonical? +- **Binary name**: `trust` (matches the old JS CLI and protocol docs)? +- **Trustcraft vs Trust Graph**: how should the names relate in the CLI, + crate names and docs? + +Everything below this line is supporting detail. + +--- + +## Context + +- The repo was last touched in September 2022. It contained a clap 3 greeter + plus a TODO list (reproduced in [Appendix A](#appendix-a-the-2022-todo-list)). + Every item on that list is covered by a phase below. +- Prior art in the `trustgraph` org that this plan builds on: + - [`trustgraph/trustgraph`](https://github.com/trustgraph/trustgraph): the + protocol. Trust Atoms, signed VC-style claims, canonical JSON, multihash IDs. + - [`trustgraph/trustgraph-schema`](https://github.com/trustgraph/trustgraph-schema): + the `TrustClaim.jsonld` context. + - [`trustgraph/js-trustgraph-cli`](https://github.com/trustgraph/js-trustgraph-cli) + (archived): `trust claim`, `trust get`, `trust map`. This is the UX to + match and improve on. + - [`trustgraph/trustgraph-holochain`](https://github.com/trustgraph/trustgraph-holochain): + Rust Trust Atoms stored as Holochain links. The tag encoding is + `Ŧ→\0content\0value\0bucket\0extra`. +- I couldn't reach trustcraft.net from the build environment (DNS lookup + failed), so I haven't seen the site or the video. This plan is based on the + repos above. Please check it against the Trustcraft vision before it's merged. + +## Design principles + +1. **Library first, CLI second.** All logic lives in library crates. The + binary only parses arguments and formats output. Other components (web, + Holochain, mobile) use the same crate instead of re-implementing the protocol. +2. **Unix pipes.** Commands read and write JSON / NDJSON on stdin/stdout, so + `trust atom create … | trust sign | trust publish --to holochain` works, and + so does piping into `jq`. This is the "spit out jsonld and optionally pipe" + item from the 2022 TODO list. +3. **Interoperable by default.** Use standards where they exist: DIDs, W3C + VC 2.0, JCS (RFC 8785) canonicalization, multihash/CID. Support Trust Graph's + own formats as conversions. +4. **Offline-capable.** Creating, signing and verifying claims never needs a + network or a backend. Backends are optional plug-ins. This answers the 2022 + question "is there a backend?" +5. **Tested at every layer.** Unit tests, golden-file tests against the + protocol examples, property tests for encode/decode round trips, and + end-to-end CLI tests. CI must stay green. + +## Target architecture + +``` +trustgraph-rust-cli/ (cargo workspace) +├── crates/ +│ ├── trustgraph-core/ TrustAtom, validation, canonical JSON, IDs (no I/O) +│ ├── trustgraph-identity/ keys, did:key, keystore, sign/verify +│ ├── trustgraph-formats/ VC 2.0 / JSON-LD, Holochain link tag, legacy TrustClaim +│ ├── trustgraph-store/ Store trait + file/SQLite impl +│ └── trustgraph-graph/ traversal, scoring, topic filters +└── src/ (bin: `trust`) clap commands → library calls → stdout +``` + +Adapters that need heavy dependencies (Holochain, IPFS) go behind cargo +features or into separate crates, so the core build stays small and fast. + +## Phases + +Each phase is one or more small PRs. A phase is done only when its acceptance +criteria pass in CI. + +### Phase 0 — Foundation ✅ (PR open) + +- clap 3 → 4.6, edition 2024, MSRV 1.85, refreshed lockfile. +- lib + bin split, error/exit-code handling (broken pipes, write errors). +- 12 unit tests and 7 end-to-end tests. CI: fmt, clippy (pedantic, `-D + warnings`), tests on three OSes, MSRV job. Dependabot. + +### Phase 1 — Core data model (`trustgraph-core`) + +- Convert to a cargo workspace and add `trustgraph-core`. +- `TrustAtom { source, target, content, value, timestamp, extra }`, with + `serde` support. Use a `Value` newtype that rejects anything outside the + agreed range and preserves the string form (e.g. `"0.999999999"`). +- `Target` accepts DIDs, URLs and other identifiers, parsed and validated. +- Canonical JSON using JCS / RFC 8785. Content ID = CIDv1 (sha2-256), so the + Qm… multihash IDs from the protocol docs can still be computed. +- **Acceptance:** golden tests reproduce the canonical JSON and hash from + the protocol README; `proptest` shows serialize → parse → serialize is stable; + no `unsafe`; 100% of public items documented. + +### Phase 2 — Identity & signing (`trustgraph-identity`) + +- Generate and import Ed25519 keys and show them as `did:key`. +- Keystore under the platform config dir (`directories` crate), with file + permissions `0600`. Optional OS keychain support via the `keyring` crate. +- Sign and verify W3C VC 2.0 credentials with the Data Integrity + `eddsa-jcs-2022` cryptosuite. This avoids full RDF canonicalization. +- **Acceptance:** sign → verify round trip; tampering with any field fails + verification; passes the published `eddsa-jcs-2022` test vectors. + +### Phase 3 — The `trust` CLI + +Rename the binary to `trust` and replace the greeter with: + +| Command | Purpose | +|---|---| +| `trust key new / list / show / export` | Manage identities | +| `trust atom create --target … --value … --content … [--tags …]` | Build an unsigned atom | +| `trust sign [--key …]` | Sign an atom or credential read from stdin | +| `trust verify` | Verify a signed claim read from stdin; exit code shows the result | +| `trust convert --to vc\|atom\|holochain-tag\|legacy-claim` | Convert between formats | +| `trust completions ` | Shell completions (`clap_complete`) | + +Also: `--output json|ndjson|pretty`, `--quiet`, structured errors (`miette` +or `anyhow` with context), and exit codes 0 for success, 1 for errors, 2 for +usage errors. Where it fits, match the archived JS CLI's flags +(`--target`, `--value`, `--tags`, `--description`) so existing docs and users +carry over. + +- **Acceptance:** `trust key new && trust atom create … | trust sign | trust + verify` succeeds end to end in an `assert_cmd` test; `--help` snapshots + are checked with `insta`. + +### Phase 4 — Storage (`trustgraph-store`) + +- `Store` trait: `put`, `get(id)`, `query(filter)`, all async-ready. +- First backend: a local append-only NDJSON or SQLite store (`trust store + add|get|ls`). +- Holochain adapter: encode and decode the existing link-tag format + (`Ŧ` header, direction byte, NUL separators, 900-byte content cap, 12-char + value cap). Start with the pure encode/decode functions. Talk to a conductor + later. +- Later: IPFS / HTTP publish, behind feature flags. +- **Acceptance:** round-trip tests against tag fixtures from + `trustgraph-holochain`'s test suite; store conformance tests that every + backend must pass. + +### Phase 5 — Graph queries (`trustgraph-graph`) + +- `trust query --source/--target/--content-prefix` (mirrors the Holochain + `QueryInput`). +- `trust map --depth N --topic sushi`: transitive trust from one identity's + point of view, with per-hop decay. This is the protocol's "cascading + network of the trust networks they are most closely connected to". +- Output as JSON, plus DOT/Mermaid for visualization. +- **Acceptance:** deterministic scores on fixture graphs, including cycles + and negative edges if Phase 1 allows them; benchmarks with `criterion` + on graphs of 100k atoms. + +### Phase 6 — Release & distribution + +- Releases with `cargo-dist` (prebuilt binaries, shell and PowerShell + installers, Homebrew tap). Versioning with `release-plz` and a generated + CHANGELOG. +- Publish the library crates to crates.io once the APIs settle (target 0.1). +- `cargo deny` (licenses and advisories) and `cargo audit` in CI. Test + coverage reporting with `cargo llvm-cov`. + +### Phase 7 — Ecosystem + +- WASM build of `trustgraph-core` + `-identity` for browser and JS clients. +- JSON Schema generated from the Rust types (`schemars`) and published with + `trustgraph-schema`. +- Update the `trustgraph/trustgraph` protocol README to point to this CLI as + the reference implementation. + +## Open decisions + +| # | Question | Recommendation | +|---|---|---| +| 1 | License for this repo (none today) | Apache-2.0, to match `trustgraph/trustgraph` | +| 2 | Value range: `0..1` (protocol README) or `-1..1` (Holochain) | `-1..1`: negative trust is useful, and `0..1` data stays valid | +| 3 | Binary name | `trust` | +| 4 | Claim format | W3C VC 2.0 + `eddsa-jcs-2022` as the main format; legacy `TrustClaim` only as a conversion | +| 5 | Repo shape | One workspace in this repo. Split crates out only if needed | +| 6 | Trustcraft naming | Waiting on your input | +| 7 | MSRV policy | Stable minus ~6 releases; raise it on purpose, never by accident | + +## Appendix A: the 2022 TODO list + +From `src/main.rs` (Sept 2022), mapped to the phases above: + +| 2022 TODO | Where it lands | +|---|---| +| decide on some initial use cases | Phase 3 command table (create / sign / verify / query / map) | +| make ArgGroup, make prompts that enforce things | Phase 3 (clap `ArgGroup`s; interactive prompts via `dialoguer` when stdin is a TTY) | +| call an API? write to trustgraph right now? | Phase 4 `Store` backends | +| what is the interface between CLI and backend? is there a backend? | Principles 1 and 4: a library API, and backends are optional | +| spit out jsonld and optionally pipe to storages | Principle 2 + Phase 4 | +| make separate components for cli, and pipes | Target architecture (workspace crates) | From 39373bf886d4125e4d0a6f9c8b30e85609112ea1 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 5 Oct 2026 22:33:51 +0000 Subject: [PATCH 02/10] Update roadmap now that the core CLI has shipped Mark what PR #11 delivered (atoms, did:key, VC 2.0 eddsa-jcs-2022, Holochain tags, store, Agent Lens) and lay out the next phases: v1 format lock, HTTPS sharing, Holochain conductor adapter, release, UX, WASM, and hardening. TL;DR and open decisions stay at the top. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UdKneRqUnsbv1t7NyvcT68 --- doc/plan/README.md | 360 +++++++++++++++++++++------------------------ 1 file changed, 170 insertions(+), 190 deletions(-) diff --git a/doc/plan/README.md b/doc/plan/README.md index f8d1d05..edb9165 100644 --- a/doc/plan/README.md +++ b/doc/plan/README.md @@ -1,36 +1,46 @@ -# Trust Graph CLI — Roadmap +# Trust Graph CLI: Roadmap ## TL;DR -**Goal:** turn this repo from a "hello world" scaffold into `trust`, the CLI and -Rust library that every other Trust Graph / Trustcraft component builds on. - -**The plan, in order:** - -1. **Foundation** (separate PR, ready): clap 4, edition 2024, lib + bin split, - 19 tests, CI on Linux/macOS/Windows, Dependabot. -2. **Core data model**: a `trustgraph-core` library crate with a typed, - validated `TrustAtom` (`source`, `target`, `content`, `value`, `timestamp`, - `extra`), canonical JSON, and content-addressed IDs. -3. **Identity & signing**: `did:key` Ed25519 identities, a local keystore, - and signed claims as W3C Verifiable Credentials 2.0 (`eddsa-jcs-2022`). -4. **Real commands**: rename the binary to `trust`; `trust key`, `trust atom - create`, `trust verify`, `trust convert`. JSON on stdout so commands pipe. -5. **Storage**: a pluggable `Store` trait; local file store first, then a - Holochain adapter that speaks the existing `trustgraph-holochain` link-tag - format. -6. **Graph queries**: `trust query` and `trust map` (transitive trust with - depth limits and topic filters). -7. **Release**: tagged releases with prebuilt binaries, crates.io, Homebrew. +**Where we are:** PR #11 turned this repo from a "hello world" scaffold into +`trust`, a working CLI and Rust library for the Trust Graph protocol. You can +create identities, sign trust ratings as W3C Verifiable Credentials, store +them, and explore them through your **Agent Lens**. It has 96 tests, CI on +three operating systems, and is checked against the W3C spec's test vectors +and `trustgraph-holochain`'s test cases. + +**What's missing:** atoms only live on your own machine. The next big step is +**sharing**: getting atoms from me to you, and back. + +**Next steps, in order:** + +1. **Lock the data format.** Publish the JSON-LD context and JSON Schema at + `trustgraph.net`, and freeze the atom and credential shapes as v1. +2. **Share over HTTPS.** `trust publish` writes a signed feed you can host + anywhere (GitHub Pages, any static host). `trust follow ` and + `trust pull` fetch other people's feeds. This gives a working network with + no servers to run. +3. **Holochain.** Read and write atoms on a live conductor using the existing + `trustgraph-holochain` zome. The link-tag codec is already done. +4. **Release.** Prebuilt binaries for macOS, Linux and Windows, Homebrew, and + `cargo install trust-cli`. Publish the `trustgraph` crate. +5. **Friendlier UX.** Interactive `trust rate`, readable table output, and + `trust lens --format dot|mermaid` to draw your graph. +6. **Embed everywhere.** A WASM build of the library for web apps, so the + Trustcraft site, browser extensions and others all use the same code. +7. **Harden.** Revoking and updating ratings, key rotation, Sybil-resistance + research for the lens, and performance at 100k+ atoms. **Decisions I need from you** (details in [Open decisions](#open-decisions)): -- **License**: this repo has none; the other `trustgraph` repos use Apache-2.0. Use that here too? -- **Value range**: the protocol README says `0..1`; `trustgraph-holochain` allows - `-0.999999999..0.999999999` (negative trust). Which is canonical? -- **Binary name**: `trust` (matches the old JS CLI and protocol docs)? -- **Trustcraft vs Trust Graph**: how should the names relate in the CLI, - crate names and docs? +- **Trustcraft vs Trust Graph:** how should the names relate in the CLI, + crates and docs? +- **Value range:** PR #11 uses `-1..=1` (from Holochain), but trustgraph.net + and the protocol README say `0..1`. Confirm, and I'll update those docs. +- **Domain for schemas:** is `https://trustgraph.net/ns/v1` OK for the + JSON-LD context? +- **Crate names:** OK to publish `trustgraph` and `trust-cli` on crates.io? + Note that an unrelated AI company is also called "TrustGraph". Everything below this line is supporting detail. @@ -38,181 +48,151 @@ Everything below this line is supporting detail. ## Context -- The repo was last touched in September 2022. It contained a clap 3 greeter - plus a TODO list (reproduced in [Appendix A](#appendix-a-the-2022-todo-list)). - Every item on that list is covered by a phase below. -- Prior art in the `trustgraph` org that this plan builds on: +- **This repo** was last touched in September 2022: a clap 3 greeter plus a + TODO list ([Appendix A](#appendix-a-the-2022-todo-list)). PR #11 covers + every item on that list. +- **Prior art** in the `trustgraph` org: - [`trustgraph/trustgraph`](https://github.com/trustgraph/trustgraph): the - protocol. Trust Atoms, signed VC-style claims, canonical JSON, multihash IDs. - - [`trustgraph/trustgraph-schema`](https://github.com/trustgraph/trustgraph-schema): - the `TrustClaim.jsonld` context. - - [`trustgraph/js-trustgraph-cli`](https://github.com/trustgraph/js-trustgraph-cli) - (archived): `trust claim`, `trust get`, `trust map`. This is the UX to - match and improve on. + protocol README (Trust Atoms, signed claims, multihash IDs). - [`trustgraph/trustgraph-holochain`](https://github.com/trustgraph/trustgraph-holochain): - Rust Trust Atoms stored as Holochain links. The tag encoding is - `Ŧ→\0content\0value\0bucket\0extra`. -- I couldn't reach trustcraft.net from the build environment (DNS lookup - failed), so I haven't seen the site or the video. This plan is based on the - repos above. Please check it against the Trustcraft vision before it's merged. + atoms stored as Holochain links (`Ŧ→content\0value\0bucket\0extra`). + - [`trustgraph/js-trustgraph-cli`](https://github.com/trustgraph/js-trustgraph-cli) + (archived): `trust claim`, `trust get`, `trust map`. + - [`trustgraph/trustgraph-schema`](https://github.com/trustgraph/trustgraph-schema): + the 2017 `TrustClaim.jsonld` context. +- **trustgraph.net** and the + [FOSDEM 2022 talk](https://archive.fosdem.org/2022/schedule/event/trustgraphs/) + describe Agents, the **Agent Lens**, the **Trust Cascade**, and trust + **rollups**. All of these are now real commands. +- I couldn't reach trustcraft.net (DNS lookup failed) or its video, so this + plan says nothing about what is specific to Trustcraft. Please check it + against that vision. + +## What shipped in PR #11 + +| Area | Status | +|---|---| +| Workspace: `trustgraph` library + `trust` binary | ✅ | +| Trust Atoms, validation, canonical JSON (RFC 8785), `Qm…` content IDs | ✅ | +| Values: exact decimals in `-1..=1`, Holochain-compatible normalization | ✅ | +| `did:key` Ed25519 identities, keystore (`0600`) | ✅ | +| W3C VC 2.0 + `eddsa-jcs-2022` sign/verify (passes the spec's test vectors) | ✅ | +| Holochain link-tag encode/decode | ✅ | +| Local append-only store, verified on the way in | ✅ | +| Agent Lens / Trust Cascade, topic filters, rollups | ✅ | +| CI (3 OSes, MSRV, clippy pedantic, rustdoc), Dependabot, Apache-2.0 | ✅ | ## Design principles -1. **Library first, CLI second.** All logic lives in library crates. The - binary only parses arguments and formats output. Other components (web, - Holochain, mobile) use the same crate instead of re-implementing the protocol. -2. **Unix pipes.** Commands read and write JSON / NDJSON on stdin/stdout, so - `trust atom create … | trust sign | trust publish --to holochain` works, and - so does piping into `jq`. This is the "spit out jsonld and optionally pipe" - item from the 2022 TODO list. -3. **Interoperable by default.** Use standards where they exist: DIDs, W3C - VC 2.0, JCS (RFC 8785) canonicalization, multihash/CID. Support Trust Graph's - own formats as conversions. -4. **Offline-capable.** Creating, signing and verifying claims never needs a - network or a backend. Backends are optional plug-ins. This answers the 2022 - question "is there a backend?" -5. **Tested at every layer.** Unit tests, golden-file tests against the - protocol examples, property tests for encode/decode round trips, and - end-to-end CLI tests. CI must stay green. - -## Target architecture - -``` -trustgraph-rust-cli/ (cargo workspace) -├── crates/ -│ ├── trustgraph-core/ TrustAtom, validation, canonical JSON, IDs (no I/O) -│ ├── trustgraph-identity/ keys, did:key, keystore, sign/verify -│ ├── trustgraph-formats/ VC 2.0 / JSON-LD, Holochain link tag, legacy TrustClaim -│ ├── trustgraph-store/ Store trait + file/SQLite impl -│ └── trustgraph-graph/ traversal, scoring, topic filters -└── src/ (bin: `trust`) clap commands → library calls → stdout -``` - -Adapters that need heavy dependencies (Holochain, IPFS) go behind cargo -features or into separate crates, so the core build stays small and fast. - -## Phases - -Each phase is one or more small PRs. A phase is done only when its acceptance -criteria pass in CI. - -### Phase 0 — Foundation ✅ (PR open) - -- clap 3 → 4.6, edition 2024, MSRV 1.85, refreshed lockfile. -- lib + bin split, error/exit-code handling (broken pipes, write errors). -- 12 unit tests and 7 end-to-end tests. CI: fmt, clippy (pedantic, `-D - warnings`), tests on three OSes, MSRV job. Dependabot. - -### Phase 1 — Core data model (`trustgraph-core`) - -- Convert to a cargo workspace and add `trustgraph-core`. -- `TrustAtom { source, target, content, value, timestamp, extra }`, with - `serde` support. Use a `Value` newtype that rejects anything outside the - agreed range and preserves the string form (e.g. `"0.999999999"`). -- `Target` accepts DIDs, URLs and other identifiers, parsed and validated. -- Canonical JSON using JCS / RFC 8785. Content ID = CIDv1 (sha2-256), so the - Qm… multihash IDs from the protocol docs can still be computed. -- **Acceptance:** golden tests reproduce the canonical JSON and hash from - the protocol README; `proptest` shows serialize → parse → serialize is stable; - no `unsafe`; 100% of public items documented. - -### Phase 2 — Identity & signing (`trustgraph-identity`) - -- Generate and import Ed25519 keys and show them as `did:key`. -- Keystore under the platform config dir (`directories` crate), with file - permissions `0600`. Optional OS keychain support via the `keyring` crate. -- Sign and verify W3C VC 2.0 credentials with the Data Integrity - `eddsa-jcs-2022` cryptosuite. This avoids full RDF canonicalization. -- **Acceptance:** sign → verify round trip; tampering with any field fails - verification; passes the published `eddsa-jcs-2022` test vectors. - -### Phase 3 — The `trust` CLI - -Rename the binary to `trust` and replace the greeter with: - -| Command | Purpose | -|---|---| -| `trust key new / list / show / export` | Manage identities | -| `trust atom create --target … --value … --content … [--tags …]` | Build an unsigned atom | -| `trust sign [--key …]` | Sign an atom or credential read from stdin | -| `trust verify` | Verify a signed claim read from stdin; exit code shows the result | -| `trust convert --to vc\|atom\|holochain-tag\|legacy-claim` | Convert between formats | -| `trust completions ` | Shell completions (`clap_complete`) | - -Also: `--output json|ndjson|pretty`, `--quiet`, structured errors (`miette` -or `anyhow` with context), and exit codes 0 for success, 1 for errors, 2 for -usage errors. Where it fits, match the archived JS CLI's flags -(`--target`, `--value`, `--tags`, `--description`) so existing docs and users -carry over. - -- **Acceptance:** `trust key new && trust atom create … | trust sign | trust - verify` succeeds end to end in an `assert_cmd` test; `--help` snapshots - are checked with `insta`. - -### Phase 4 — Storage (`trustgraph-store`) - -- `Store` trait: `put`, `get(id)`, `query(filter)`, all async-ready. -- First backend: a local append-only NDJSON or SQLite store (`trust store - add|get|ls`). -- Holochain adapter: encode and decode the existing link-tag format - (`Ŧ` header, direction byte, NUL separators, 900-byte content cap, 12-char - value cap). Start with the pure encode/decode functions. Talk to a conductor - later. -- Later: IPFS / HTTP publish, behind feature flags. -- **Acceptance:** round-trip tests against tag fixtures from - `trustgraph-holochain`'s test suite; store conformance tests that every - backend must pass. - -### Phase 5 — Graph queries (`trustgraph-graph`) - -- `trust query --source/--target/--content-prefix` (mirrors the Holochain - `QueryInput`). -- `trust map --depth N --topic sushi`: transitive trust from one identity's - point of view, with per-hop decay. This is the protocol's "cascading - network of the trust networks they are most closely connected to". -- Output as JSON, plus DOT/Mermaid for visualization. -- **Acceptance:** deterministic scores on fixture graphs, including cycles - and negative edges if Phase 1 allows them; benchmarks with `criterion` - on graphs of 100k atoms. - -### Phase 6 — Release & distribution - -- Releases with `cargo-dist` (prebuilt binaries, shell and PowerShell - installers, Homebrew tap). Versioning with `release-plz` and a generated - CHANGELOG. -- Publish the library crates to crates.io once the APIs settle (target 0.1). -- `cargo deny` (licenses and advisories) and `cargo audit` in CI. Test - coverage reporting with `cargo llvm-cov`. - -### Phase 7 — Ecosystem - -- WASM build of `trustgraph-core` + `-identity` for browser and JS clients. -- JSON Schema generated from the Rust types (`schemars`) and published with - `trustgraph-schema`. -- Update the `trustgraph/trustgraph` protocol README to point to this CLI as - the reference implementation. +1. **Library first.** All protocol logic lives in `trustgraph`, which has no + CLI dependencies. Every other component (web, Holochain, mobile, Trustcraft) + uses the same code instead of re-implementing the protocol. +2. **Unix pipes.** JSON/NDJSON in and out, so commands compose: + `trust lens --rollup | trust sign | trust add`. +3. **Standards over invention.** DIDs, VC 2.0, Data Integrity, JCS, multihash. + Trust Graph's own formats are conversions on top. +4. **Offline first, servers optional.** Creating, signing, verifying and + exploring never need the network. Sharing is a plug-in. +5. **Agent-centric.** There is no global score, ever. Every result is from + someone's point of view. +6. **Proven, not hoped.** Every format has spec vectors, property tests, or + cross-implementation fixtures, and CI stays green. + +## Next phases + +Each phase is a few small PRs, and is done only when its acceptance criteria +pass in CI. + +### 1. Lock the v1 data format + +- Publish `https://trustgraph.net/ns/v1` (JSON-LD context) and a JSON Schema + generated from the Rust types (`schemars`), in `trustgraph-schema`. +- Document the atom and credential formats in the protocol README, replacing + the 2017 `TrustClaim` example, and update trustgraph.net to match the + decided value range. +- Add golden files of real atoms and credentials to the repo; CI fails if + the bytes ever change. +- **Acceptance:** an off-the-shelf VC library (e.g. Digital Bazaar's + `@digitalbazaar/vc` with the `eddsa-jcs-2022` suite) verifies a credential + signed by `trust`. + +### 2. Share over HTTPS + +- `trust publish [--out DIR]`: write your signed atoms as a static feed + (`atoms.ndjson` plus a small signed index) that any static host can serve. +- `trust follow ` / `trust unfollow` / `trust pull`: fetch feeds and + verify every atom before storing it. Use ETags so repeat pulls are cheap. +- Optional discovery via `/.well-known/trust/atoms.ndjson`, plus `did:web` so + an organization can sign with its own domain. +- **Acceptance:** two machines exchange atoms through GitHub Pages, and each + sees the other in `trust lens`. + +### 3. Holochain + +- An adapter behind a cargo feature (`--features holochain`) that talks to a + conductor through `holochain_client`: `trust publish --to holochain`, + `trust pull --from holochain`. +- Map `did:key` identities to Holochain agent keys (both are Ed25519). +- Upstream fix: for tiny values, `trustgraph-holochain`'s value strings can + exceed the documented 12-character limit (`-.00000000100000000`). `trust` + falls back to nine decimal places for these; align the zome to match. +- **Acceptance:** an atom created by `trust` round-trips through a real + conductor in an integration test (nix or a container in CI). + +### 4. Release + +- `cargo-dist` for prebuilt binaries and shell/PowerShell installers, plus a + Homebrew tap. `release-plz` for versioning and the CHANGELOG. +- Publish `trustgraph` and `trust-cli` on crates.io once Phase 1 is frozen. +- `cargo deny` (licenses and advisories) and coverage (`cargo llvm-cov`) in CI. + +### 5. Friendlier UX + +- `trust rate`: interactive prompts when stdin is a TTY (the 2022 TODO list's + "prompts that enforce things"), using `dialoguer`. +- `--format table` for humans; JSON stays the default when piped. +- `trust lens --format dot|mermaid` to draw your trust graph. +- Named contacts (`trust contact add bob did:key:…`) so you don't paste DIDs. + +### 6. Embed everywhere + +- Compile `trustgraph` to WASM (`wasm-bindgen`) and publish an npm package + for web clients, including Trustcraft. +- Optional C ABI or UniFFI bindings for mobile. + +### 7. Harden + +- **Revocation and updates:** a newer atom from the same source replaces an + older one (the lens already prefers the latest); add explicit revocation + atoms and Bitstring Status Lists for credentials. +- **Key rotation:** `did:key` can't rotate. Support `did:web` and/or `did:plc`, + with signed key-succession statements. +- **Lens research:** compare the cascade with EigenTrust and Appleseed; study + Sybil resistance; add `criterion` benchmarks on 100k+ atom graphs. +- **Privacy:** private atoms (encrypted to recipients) and selective sharing, + as the protocol README calls for. ## Open decisions | # | Question | Recommendation | |---|---|---| -| 1 | License for this repo (none today) | Apache-2.0, to match `trustgraph/trustgraph` | -| 2 | Value range: `0..1` (protocol README) or `-1..1` (Holochain) | `-1..1`: negative trust is useful, and `0..1` data stays valid | -| 3 | Binary name | `trust` | -| 4 | Claim format | W3C VC 2.0 + `eddsa-jcs-2022` as the main format; legacy `TrustClaim` only as a conversion | -| 5 | Repo shape | One workspace in this repo. Split crates out only if needed | -| 6 | Trustcraft naming | Waiting on your input | -| 7 | MSRV policy | Stable minus ~6 releases; raise it on purpose, never by accident | +| 1 | How Trustcraft and Trust Graph relate | Waiting on you | +| 2 | Value range | Keep `-1..=1`; `0..1` data is still valid. Update the website and protocol README | +| 3 | JSON-LD context URL | `https://trustgraph.net/ns/v1` | +| 4 | Crate names | `trustgraph` (library) and `trust-cli` (binary `trust`) | +| 5 | Copyright line in LICENSE | Currently the unfilled Apache template; e.g. "Trust Graph contributors" | +| 6 | Sharing transport order | HTTPS feeds first (no servers), then Holochain | +| 7 | MSRV policy | Stable minus about 6 releases; raise it on purpose, never by accident | ## Appendix A: the 2022 TODO list -From `src/main.rs` (Sept 2022), mapped to the phases above: +From `src/main.rs` (September 2022): -| 2022 TODO | Where it lands | +| 2022 TODO | Status | |---|---| -| decide on some initial use cases | Phase 3 command table (create / sign / verify / query / map) | -| make ArgGroup, make prompts that enforce things | Phase 3 (clap `ArgGroup`s; interactive prompts via `dialoguer` when stdin is a TTY) | -| call an API? write to trustgraph right now? | Phase 4 `Store` backends | -| what is the interface between CLI and backend? is there a backend? | Principles 1 and 4: a library API, and backends are optional | -| spit out jsonld and optionally pipe to storages | Principle 2 + Phase 4 | -| make separate components for cli, and pipes | Target architecture (workspace crates) | +| decide on some initial use cases | ✅ rate, sign, verify, store, query, lens (PR #11) | +| make ArgGroup, make prompts that enforce things | ✅ validation in PR #11; interactive prompts in Phase 5 | +| call an API? write to trustgraph right now? | Phases 2 and 3 | +| what is the interface between CLI and backend? is there a backend? | ✅ The library is the interface; backends are optional plug-ins | +| spit out jsonld and optionally pipe to storages | ✅ VC 2.0 JSON-LD on stdout; `trust add` stores it | +| make separate components for cli, and pipes | ✅ `trustgraph` library + `trust` binary | From 657184c52eb3bfb6852b4d783bb01d93830d26a5 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 5 Oct 2026 22:48:31 +0000 Subject: [PATCH 03/10] Remove Trustcraft references from the roadmap The project is Trust Graph; Trustcraft is not a thing. Drop the naming decision and the trustcraft.net note, point the WASM consumer at trustgraph.net, renumber the open decisions, and link PR #11. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UdKneRqUnsbv1t7NyvcT68 --- doc/plan/README.md | 36 +++++++++++++++--------------------- 1 file changed, 15 insertions(+), 21 deletions(-) diff --git a/doc/plan/README.md b/doc/plan/README.md index edb9165..8f82ff4 100644 --- a/doc/plan/README.md +++ b/doc/plan/README.md @@ -2,7 +2,7 @@ ## TL;DR -**Where we are:** PR #11 turned this repo from a "hello world" scaffold into +**Where we are:** [PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11) turned this repo from a "hello world" scaffold into `trust`, a working CLI and Rust library for the Trust Graph protocol. You can create identities, sign trust ratings as W3C Verifiable Credentials, store them, and explore them through your **Agent Lens**. It has 96 tests, CI on @@ -27,15 +27,13 @@ and `trustgraph-holochain`'s test cases. 5. **Friendlier UX.** Interactive `trust rate`, readable table output, and `trust lens --format dot|mermaid` to draw your graph. 6. **Embed everywhere.** A WASM build of the library for web apps, so the - Trustcraft site, browser extensions and others all use the same code. + trustgraph.net, browser extensions and others all use the same code. 7. **Harden.** Revoking and updating ratings, key rotation, Sybil-resistance research for the lens, and performance at 100k+ atoms. **Decisions I need from you** (details in [Open decisions](#open-decisions)): -- **Trustcraft vs Trust Graph:** how should the names relate in the CLI, - crates and docs? -- **Value range:** PR #11 uses `-1..=1` (from Holochain), but trustgraph.net +- **Value range:** [PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11) uses `-1..=1` (from Holochain), but trustgraph.net and the protocol README say `0..1`. Confirm, and I'll update those docs. - **Domain for schemas:** is `https://trustgraph.net/ns/v1` OK for the JSON-LD context? @@ -49,7 +47,7 @@ Everything below this line is supporting detail. ## Context - **This repo** was last touched in September 2022: a clap 3 greeter plus a - TODO list ([Appendix A](#appendix-a-the-2022-todo-list)). PR #11 covers + TODO list ([Appendix A](#appendix-a-the-2022-todo-list)). [PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11) covers every item on that list. - **Prior art** in the `trustgraph` org: - [`trustgraph/trustgraph`](https://github.com/trustgraph/trustgraph): the @@ -64,11 +62,8 @@ Everything below this line is supporting detail. [FOSDEM 2022 talk](https://archive.fosdem.org/2022/schedule/event/trustgraphs/) describe Agents, the **Agent Lens**, the **Trust Cascade**, and trust **rollups**. All of these are now real commands. -- I couldn't reach trustcraft.net (DNS lookup failed) or its video, so this - plan says nothing about what is specific to Trustcraft. Please check it - against that vision. -## What shipped in PR #11 +## What shipped in [PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11) | Area | Status | |---|---| @@ -85,7 +80,7 @@ Everything below this line is supporting detail. ## Design principles 1. **Library first.** All protocol logic lives in `trustgraph`, which has no - CLI dependencies. Every other component (web, Holochain, mobile, Trustcraft) + CLI dependencies. Every other component (web, Holochain, mobile) uses the same code instead of re-implementing the protocol. 2. **Unix pipes.** JSON/NDJSON in and out, so commands compose: `trust lens --rollup | trust sign | trust add`. @@ -157,7 +152,7 @@ pass in CI. ### 6. Embed everywhere - Compile `trustgraph` to WASM (`wasm-bindgen`) and publish an npm package - for web clients, including Trustcraft. + for web clients, including trustgraph.net. - Optional C ABI or UniFFI bindings for mobile. ### 7. Harden @@ -176,13 +171,12 @@ pass in CI. | # | Question | Recommendation | |---|---|---| -| 1 | How Trustcraft and Trust Graph relate | Waiting on you | -| 2 | Value range | Keep `-1..=1`; `0..1` data is still valid. Update the website and protocol README | -| 3 | JSON-LD context URL | `https://trustgraph.net/ns/v1` | -| 4 | Crate names | `trustgraph` (library) and `trust-cli` (binary `trust`) | -| 5 | Copyright line in LICENSE | Currently the unfilled Apache template; e.g. "Trust Graph contributors" | -| 6 | Sharing transport order | HTTPS feeds first (no servers), then Holochain | -| 7 | MSRV policy | Stable minus about 6 releases; raise it on purpose, never by accident | +| 1 | Value range | Keep `-1..=1`; `0..1` data is still valid. Update the website and protocol README | +| 2 | JSON-LD context URL | `https://trustgraph.net/ns/v1` | +| 3 | Crate names | `trustgraph` (library) and `trust-cli` (binary `trust`) | +| 4 | Copyright line in LICENSE | Currently the unfilled Apache template; e.g. "Trust Graph contributors" | +| 5 | Sharing transport order | HTTPS feeds first (no servers), then Holochain | +| 6 | MSRV policy | Stable minus about 6 releases; raise it on purpose, never by accident | ## Appendix A: the 2022 TODO list @@ -190,8 +184,8 @@ From `src/main.rs` (September 2022): | 2022 TODO | Status | |---|---| -| decide on some initial use cases | ✅ rate, sign, verify, store, query, lens (PR #11) | -| make ArgGroup, make prompts that enforce things | ✅ validation in PR #11; interactive prompts in Phase 5 | +| decide on some initial use cases | ✅ rate, sign, verify, store, query, lens ([PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11)) | +| make ArgGroup, make prompts that enforce things | ✅ validation in [PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11); interactive prompts in Phase 5 | | call an API? write to trustgraph right now? | Phases 2 and 3 | | what is the interface between CLI and backend? is there a backend? | ✅ The library is the interface; backends are optional plug-ins | | spit out jsonld and optionally pipe to storages | ✅ VC 2.0 JSON-LD on stdout; `trust add` stores it | From a78b60bffd1ed962e78ba3de7d48acfce28a1d1e Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 6 Oct 2026 20:39:15 +0000 Subject: [PATCH 04/10] Roadmap: adopt the pure-core architecture Reflect PR #15 (pure trustgraph-core with CLI, WebAssembly and Node wrappers): add it to what has shipped, make 'one pure core, thin wrappers' the first principle, fold 'Embed everywhere' into a new 'Release and publish' phase (npm per-platform packages, wasm package, Convex spike), and add the package-name and public/private npm decisions. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UdKneRqUnsbv1t7NyvcT68 --- doc/plan/README.md | 111 +++++++++++++++++++++++++++------------------ 1 file changed, 68 insertions(+), 43 deletions(-) diff --git a/doc/plan/README.md b/doc/plan/README.md index 8f82ff4..6414188 100644 --- a/doc/plan/README.md +++ b/doc/plan/README.md @@ -1,35 +1,37 @@ -# Trust Graph CLI: Roadmap +# Trust Graph: Roadmap ## TL;DR **Where we are:** [PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11) turned this repo from a "hello world" scaffold into `trust`, a working CLI and Rust library for the Trust Graph protocol. You can create identities, sign trust ratings as W3C Verifiable Credentials, store -them, and explore them through your **Agent Lens**. It has 96 tests, CI on -three operating systems, and is checked against the W3C spec's test vectors -and `trustgraph-holochain`'s test cases. +them, and explore them through your **Agent Lens**. [PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15) then split it into +**one pure Rust core with three thin wrappers**: the `trust` CLI, a +WebAssembly package (browsers, Workers, Convex queries) and a native Node +module (Node, Convex Node actions). See [architecture](../architecture.md). -**What's missing:** atoms only live on your own machine. The next big step is -**sharing**: getting atoms from me to you, and back. +**What's missing:** nothing is published yet, and atoms only live where you +put them. The next big steps are **publishing the packages** so CoreNexus and +others can use them, then **sharing** atoms between people. **Next steps, in order:** 1. **Lock the data format.** Publish the JSON-LD context and JSON Schema at `trustgraph.net`, and freeze the atom and credential shapes as v1. -2. **Share over HTTPS.** `trust publish` writes a signed feed you can host +2. **Release and publish.** Prebuilt `trust` binaries (cargo-dist, Homebrew), + the npm packages (`@trustgraph/trustgraph` per-platform via napi-rs, and + `@trustgraph/trustgraph-wasm`), and the crates. Prove the WebAssembly + build inside a real Convex query. +3. **Share over HTTPS.** `trust publish` writes a signed feed you can host anywhere (GitHub Pages, any static host). `trust follow ` and `trust pull` fetch other people's feeds. This gives a working network with no servers to run. -3. **Holochain.** Read and write atoms on a live conductor using the existing +4. **Holochain.** Read and write atoms on a live conductor using the existing `trustgraph-holochain` zome. The link-tag codec is already done. -4. **Release.** Prebuilt binaries for macOS, Linux and Windows, Homebrew, and - `cargo install trust-cli`. Publish the `trustgraph` crate. 5. **Friendlier UX.** Interactive `trust rate`, readable table output, and `trust lens --format dot|mermaid` to draw your graph. -6. **Embed everywhere.** A WASM build of the library for web apps, so the - trustgraph.net, browser extensions and others all use the same code. -7. **Harden.** Revoking and updating ratings, key rotation, Sybil-resistance - research for the lens, and performance at 100k+ atoms. +6. **Harden.** Revoking and updating ratings, key rotation, Sybil-resistance + research for the lens, and performance beyond 100k atoms. **Decisions I need from you** (details in [Open decisions](#open-decisions)): @@ -37,8 +39,12 @@ and `trustgraph-holochain`'s test cases. and the protocol README say `0..1`. Confirm, and I'll update those docs. - **Domain for schemas:** is `https://trustgraph.net/ns/v1` OK for the JSON-LD context? -- **Crate names:** OK to publish `trustgraph` and `trust-cli` on crates.io? - Note that an unrelated AI company is also called "TrustGraph". +- **Package names:** OK to publish `trustgraph-core` and `trustgraph-cli` on + crates.io, and `@trustgraph/trustgraph` and `@trustgraph/trustgraph-wasm` + on npm? An unrelated AI company is also called "TrustGraph". +- **Public or private npm:** Convex installs native packages from npm at + deploy time. Public is simplest; private needs a test that Convex can + install from a private registry first. Everything below this line is supporting detail. @@ -63,11 +69,11 @@ Everything below this line is supporting detail. describe Agents, the **Agent Lens**, the **Trust Cascade**, and trust **rollups**. All of these are now real commands. -## What shipped in [PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11) +## What has shipped | Area | Status | |---|---| -| Workspace: `trustgraph` library + `trust` binary | ✅ | +| Workspace: protocol library + `trust` binary ([PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11)) | ✅ | | Trust Atoms, validation, canonical JSON (RFC 8785), `Qm…` content IDs | ✅ | | Values: exact decimals in `-1..=1`, Holochain-compatible normalization | ✅ | | `did:key` Ed25519 identities, keystore (`0600`) | ✅ | @@ -76,12 +82,20 @@ Everything below this line is supporting detail. | Local append-only store, verified on the way in | ✅ | | Agent Lens / Trust Cascade, topic filters, rollups | ✅ | | CI (3 OSes, MSRV, clippy pedantic, rustdoc), Dependabot, Apache-2.0 | ✅ | +| Pure `trustgraph-core` (no I/O, enforced in CI) + shared JSON `api` ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ | +| `@trustgraph/trustgraph-wasm`: web and Node builds, 547 KiB ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ built and tested, not published | +| `@trustgraph/trustgraph`: napi-rs, tested on Linux, macOS, Windows ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ built and tested, not published | +| Shared TypeScript types; one smoke test across all JS builds ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ | +| `lens` on 100k atoms: 0.78 s WebAssembly, 0.48 s native ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ | ## Design principles -1. **Library first.** All protocol logic lives in `trustgraph`, which has no - CLI dependencies. Every other component (web, Holochain, mobile) - uses the same code instead of re-implementing the protocol. +1. **One pure core, thin wrappers.** All protocol logic lives in + `trustgraph-core`, which does no I/O (no files, network, clock or + randomness). The CLI, WebAssembly and Node packages only move data in and + out. Every other component (web, Holochain, CoreNexus, mobile) uses the + same code instead of re-implementing the protocol, and no host (Convex + included) shapes the core. See [architecture](../architecture.md). 2. **Unix pipes.** JSON/NDJSON in and out, so commands compose: `trust lens --rollup | trust sign | trust add`. 3. **Standards over invention.** DIDs, VC 2.0, Data Integrity, JCS, multihash. @@ -111,7 +125,29 @@ pass in CI. `@digitalbazaar/vc` with the `eddsa-jcs-2022` suite) verifies a credential signed by `trust`. -### 2. Share over HTTPS +### 2. Release and publish + +- **CLI:** `cargo-dist` for prebuilt binaries and shell/PowerShell + installers, plus a Homebrew tap. `release-plz` for versioning and the + CHANGELOG. +- **npm, native:** add the napi-rs cross-compile matrix (the targets are + already listed in `crates/trustgraph-node/package.json`) and publish + `@trustgraph/trustgraph` with one small package per platform, like + `@resvg/resvg-js`. +- **npm, WebAssembly:** publish `@trustgraph/trustgraph-wasm` from + `scripts/build-wasm-package.sh`. +- **Crates:** publish `trustgraph-core` and `trustgraph-cli` once Phase 1 is + frozen. +- **Convex spike:** deploy a query that imports the WebAssembly package and + runs `lens`; confirm bundle size and cold-start time in Convex itself. + Then use the native package from a Node action via `externalPackages`. +- `cargo deny` (licenses and advisories) and coverage (`cargo llvm-cov`) in CI. +- Later: a UniFFI wrapper for mobile, on the same core. +- **Acceptance:** `npm install @trustgraph/trustgraph` works on macOS, Linux + and Windows without a Rust toolchain, and a Convex deployment computes a + lens in a query. + +### 3. Share over HTTPS - `trust publish [--out DIR]`: write your signed atoms as a static feed (`atoms.ndjson` plus a small signed index) that any static host can serve. @@ -122,7 +158,7 @@ pass in CI. - **Acceptance:** two machines exchange atoms through GitHub Pages, and each sees the other in `trust lens`. -### 3. Holochain +### 4. Holochain - An adapter behind a cargo feature (`--features holochain`) that talks to a conductor through `holochain_client`: `trust publish --to holochain`, @@ -134,13 +170,6 @@ pass in CI. - **Acceptance:** an atom created by `trust` round-trips through a real conductor in an integration test (nix or a container in CI). -### 4. Release - -- `cargo-dist` for prebuilt binaries and shell/PowerShell installers, plus a - Homebrew tap. `release-plz` for versioning and the CHANGELOG. -- Publish `trustgraph` and `trust-cli` on crates.io once Phase 1 is frozen. -- `cargo deny` (licenses and advisories) and coverage (`cargo llvm-cov`) in CI. - ### 5. Friendlier UX - `trust rate`: interactive prompts when stdin is a TTY (the 2022 TODO list's @@ -149,13 +178,7 @@ pass in CI. - `trust lens --format dot|mermaid` to draw your trust graph. - Named contacts (`trust contact add bob did:key:…`) so you don't paste DIDs. -### 6. Embed everywhere - -- Compile `trustgraph` to WASM (`wasm-bindgen`) and publish an npm package - for web clients, including trustgraph.net. -- Optional C ABI or UniFFI bindings for mobile. - -### 7. Harden +### 6. Harden - **Revocation and updates:** a newer atom from the same source replaces an older one (the lens already prefers the latest); add explicit revocation @@ -163,7 +186,8 @@ pass in CI. - **Key rotation:** `did:key` can't rotate. Support `did:web` and/or `did:plc`, with signed key-succession statements. - **Lens research:** compare the cascade with EigenTrust and Appleseed; study - Sybil resistance; add `criterion` benchmarks on 100k+ atom graphs. + Sybil resistance; add `criterion` benchmarks, and an incremental lens for + graphs well beyond 100k atoms (today: precompute rollups natively). - **Privacy:** private atoms (encrypted to recipients) and selective sharing, as the protocol README calls for. @@ -173,10 +197,11 @@ pass in CI. |---|---|---| | 1 | Value range | Keep `-1..=1`; `0..1` data is still valid. Update the website and protocol README | | 2 | JSON-LD context URL | `https://trustgraph.net/ns/v1` | -| 3 | Crate names | `trustgraph` (library) and `trust-cli` (binary `trust`) | -| 4 | Copyright line in LICENSE | Currently the unfilled Apache template; e.g. "Trust Graph contributors" | -| 5 | Sharing transport order | HTTPS feeds first (no servers), then Holochain | -| 6 | MSRV policy | Stable minus about 6 releases; raise it on purpose, never by accident | +| 3 | Package names | crates `trustgraph-core`, `trustgraph-cli` (binary `trust`); npm `@trustgraph/trustgraph`, `@trustgraph/trustgraph-wasm` | +| 4 | Public or private npm | Public: Convex installs native packages from npm at deploy time | +| 5 | Copyright line in LICENSE | Currently the unfilled Apache template; e.g. "Trust Graph contributors" | +| 6 | Sharing transport order | HTTPS feeds first (no servers), then Holochain | +| 7 | MSRV policy | Stable minus about 6 releases; raise it on purpose, never by accident | ## Appendix A: the 2022 TODO list @@ -189,4 +214,4 @@ From `src/main.rs` (September 2022): | call an API? write to trustgraph right now? | Phases 2 and 3 | | what is the interface between CLI and backend? is there a backend? | ✅ The library is the interface; backends are optional plug-ins | | spit out jsonld and optionally pipe to storages | ✅ VC 2.0 JSON-LD on stdout; `trust add` stores it | -| make separate components for cli, and pipes | ✅ `trustgraph` library + `trust` binary | +| make separate components for cli, and pipes | ✅ pure core + CLI, WebAssembly and Node wrappers ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | From ab92a548efbe59047605560bc789602a42929e00 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 6 Oct 2026 21:26:45 +0000 Subject: [PATCH 05/10] Roadmap: this repo becomes the Trust Graph monorepo Add Phase 0: bring the protocol README, JSON-LD schema and Holochain zome in with history, archive the old repos, and rename this repo to trustgraph/trustgraph (after moving the existing repo of that name aside). Add 'one repo, Rust first' as the first design principle and the rename as an open decision. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UdKneRqUnsbv1t7NyvcT68 --- doc/plan/README.md | 54 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 46 insertions(+), 8 deletions(-) diff --git a/doc/plan/README.md b/doc/plan/README.md index 6414188..ef71914 100644 --- a/doc/plan/README.md +++ b/doc/plan/README.md @@ -14,8 +14,15 @@ module (Node, Convex Node actions). See [architecture](../architecture.md). put them. The next big steps are **publishing the packages** so CoreNexus and others can use them, then **sharing** atoms between people. +**This repo is the Trust Graph monorepo.** Every Trust Graph project lives +here: Rust first, TypeScript where it fits, with all protocol logic in one +Rust core. It will be renamed to `trustgraph/trustgraph`. + **Next steps, in order:** +0. **Become the monorepo.** Bring in the protocol docs, the JSON-LD schema and + the Holochain zome from their separate repos, archive the old ones, and + rename this repo to `trustgraph/trustgraph`. 1. **Lock the data format.** Publish the JSON-LD context and JSON Schema at `trustgraph.net`, and freeze the atom and credential shapes as v1. 2. **Release and publish.** Prebuilt `trust` binaries (cargo-dist, Homebrew), @@ -26,8 +33,9 @@ others can use them, then **sharing** atoms between people. anywhere (GitHub Pages, any static host). `trust follow ` and `trust pull` fetch other people's feeds. This gives a working network with no servers to run. -4. **Holochain.** Read and write atoms on a live conductor using the existing - `trustgraph-holochain` zome. The link-tag codec is already done. +4. **Holochain.** Read and write atoms on a live conductor using the + `trustgraph-holochain` zome (moved into `holochain/` in Phase 0). The + link-tag codec is already done. 5. **Friendlier UX.** Interactive `trust rate`, readable table output, and `trust lens --format dot|mermaid` to draw your graph. 6. **Harden.** Revoking and updating ratings, key rotation, Sybil-resistance @@ -45,6 +53,10 @@ others can use them, then **sharing** atoms between people. - **Public or private npm:** Convex installs native packages from npm at deploy time. Public is simplest; private needs a test that Convex can install from a private registry first. +- **The existing `trustgraph/trustgraph` repo:** that name is taken by the + protocol README repo. To rename this repo to `trustgraph/trustgraph`, first + move that README in here (Phase 0), then rename the old repo to + `trustgraph-protocol-archive` and archive it. Everything below this line is supporting detail. @@ -90,21 +102,24 @@ Everything below this line is supporting detail. ## Design principles -1. **One pure core, thin wrappers.** All protocol logic lives in +1. **One repo, Rust first.** Every Trust Graph project lives in this + monorepo. Protocol logic is Rust; TypeScript is welcome where it fits (web, + Convex, extensions) but always calls the core rather than re-implementing it. +2. **One pure core, thin wrappers.** All protocol logic lives in `trustgraph-core`, which does no I/O (no files, network, clock or randomness). The CLI, WebAssembly and Node packages only move data in and out. Every other component (web, Holochain, CoreNexus, mobile) uses the same code instead of re-implementing the protocol, and no host (Convex included) shapes the core. See [architecture](../architecture.md). -2. **Unix pipes.** JSON/NDJSON in and out, so commands compose: +3. **Unix pipes.** JSON/NDJSON in and out, so commands compose: `trust lens --rollup | trust sign | trust add`. -3. **Standards over invention.** DIDs, VC 2.0, Data Integrity, JCS, multihash. +4. **Standards over invention.** DIDs, VC 2.0, Data Integrity, JCS, multihash. Trust Graph's own formats are conversions on top. -4. **Offline first, servers optional.** Creating, signing, verifying and +5. **Offline first, servers optional.** Creating, signing, verifying and exploring never need the network. Sharing is a plug-in. -5. **Agent-centric.** There is no global score, ever. Every result is from +6. **Agent-centric.** There is no global score, ever. Every result is from someone's point of view. -6. **Proven, not hoped.** Every format has spec vectors, property tests, or +7. **Proven, not hoped.** Every format has spec vectors, property tests, or cross-implementation fixtures, and CI stays green. ## Next phases @@ -112,6 +127,28 @@ Everything below this line is supporting detail. Each phase is a few small PRs, and is done only when its acceptance criteria pass in CI. +### 0. Become the monorepo + +One repository for every Trust Graph project, so the core and everything +built on it change together, in one PR and one CI run. + +| Today | Moves to | Then | +|---|---|---| +| [`trustgraph/trustgraph`](https://github.com/trustgraph/trustgraph) (protocol README) | `doc/protocol.md`, updated to the current atom and credential formats | Rename the old repo to `trustgraph-protocol-archive` and archive it | +| [`trustgraph/trustgraph-schema`](https://github.com/trustgraph/trustgraph-schema) (JSON-LD) | `schema/`, alongside the new v1 context (Phase 1) | Archive; keep GitHub Pages serving the old URL, or redirect it | +| [`trustgraph/trustgraph-holochain`](https://github.com/trustgraph/trustgraph-holochain) (zome) | `holochain/`, its own Cargo workspace (zomes pin `hdk` versions and build for Holochain's WebAssembly target), using `trustgraph-core` for the tag codec | Archive once the zome builds and tests here | +| [`trustgraph/js-trustgraph-cli`](https://github.com/trustgraph/js-trustgraph-cli) | Nothing: `trust` replaces it | Already archived | +| This repo, `trustgraph-rust-cli` | | Rename to `trustgraph/trustgraph`. GitHub redirects the old URLs | + +- Import with history (`git subtree add` or `git filter-repo`), so blame and + past discussion survive. +- Layout rules: Rust crates in `crates/*` (one Cargo workspace), TypeScript + packages in `packages/*` (one npm workspace), docs in `doc/`. TypeScript + calls the core through the WebAssembly or native package and never + re-implements protocol logic. +- **Acceptance:** one `cargo test` and one CI run cover the core, the CLI, the + bindings and the Holochain zome; the old repos are archived and point here. + ### 1. Lock the v1 data format - Publish `https://trustgraph.net/ns/v1` (JSON-LD context) and a JSON Schema @@ -202,6 +239,7 @@ pass in CI. | 5 | Copyright line in LICENSE | Currently the unfilled Apache template; e.g. "Trust Graph contributors" | | 6 | Sharing transport order | HTTPS feeds first (no servers), then Holochain | | 7 | MSRV policy | Stable minus about 6 releases; raise it on purpose, never by accident | +| 8 | The existing `trustgraph/trustgraph` repo | Move its README into `doc/protocol.md`, rename it `trustgraph-protocol-archive`, archive it, then rename this repo to `trustgraph/trustgraph` | ## Appendix A: the 2022 TODO list From 3919ed8b15b0a6db65774577d1b7c8b953610360 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 6 Oct 2026 21:28:38 +0000 Subject: [PATCH 06/10] Roadmap: the TypeScript workspace uses pnpm Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UdKneRqUnsbv1t7NyvcT68 --- doc/plan/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/plan/README.md b/doc/plan/README.md index ef71914..ae2ea34 100644 --- a/doc/plan/README.md +++ b/doc/plan/README.md @@ -143,7 +143,7 @@ built on it change together, in one PR and one CI run. - Import with history (`git subtree add` or `git filter-repo`), so blame and past discussion survive. - Layout rules: Rust crates in `crates/*` (one Cargo workspace), TypeScript - packages in `packages/*` (one npm workspace), docs in `doc/`. TypeScript + packages in `packages/*` (one pnpm workspace), docs in `doc/`. TypeScript calls the core through the WebAssembly or native package and never re-implements protocol logic. - **Acceptance:** one `cargo test` and one CI run cover the core, the CLI, the From e3403673dc4a6d82d8f117e5519761d83093e6a6 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 6 Oct 2026 21:48:19 +0000 Subject: [PATCH 07/10] Roadmap: benchmark figures on Node 24 LTS Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UdKneRqUnsbv1t7NyvcT68 --- doc/plan/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/plan/README.md b/doc/plan/README.md index ae2ea34..4b0d69c 100644 --- a/doc/plan/README.md +++ b/doc/plan/README.md @@ -98,7 +98,7 @@ Everything below this line is supporting detail. | `@trustgraph/trustgraph-wasm`: web and Node builds, 547 KiB ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ built and tested, not published | | `@trustgraph/trustgraph`: napi-rs, tested on Linux, macOS, Windows ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ built and tested, not published | | Shared TypeScript types; one smoke test across all JS builds ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ | -| `lens` on 100k atoms: 0.78 s WebAssembly, 0.48 s native ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ | +| `lens` on 100k atoms (Node 24 LTS): 0.54 s WebAssembly, 0.43 s native ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ | ## Design principles From 9942e9777e7e0f6bcebf5d5deab5e23968c0d273 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 6 Oct 2026 22:37:37 +0000 Subject: [PATCH 08/10] Roadmap: remove Holochain Drop the Holochain phase, the zome move from Phase 0, and Holochain mentions in the context, status table, principles and decisions. Renumber the phases (UX is now 4, Harden 5). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UdKneRqUnsbv1t7NyvcT68 --- doc/plan/README.md | 47 ++++++++++++++-------------------------------- 1 file changed, 14 insertions(+), 33 deletions(-) diff --git a/doc/plan/README.md b/doc/plan/README.md index 4b0d69c..2e525d4 100644 --- a/doc/plan/README.md +++ b/doc/plan/README.md @@ -20,9 +20,9 @@ Rust core. It will be renamed to `trustgraph/trustgraph`. **Next steps, in order:** -0. **Become the monorepo.** Bring in the protocol docs, the JSON-LD schema and - the Holochain zome from their separate repos, archive the old ones, and - rename this repo to `trustgraph/trustgraph`. +0. **Become the monorepo.** Bring in the protocol docs and the JSON-LD schema + from their separate repos, archive the old ones, and rename this repo to + `trustgraph/trustgraph`. 1. **Lock the data format.** Publish the JSON-LD context and JSON Schema at `trustgraph.net`, and freeze the atom and credential shapes as v1. 2. **Release and publish.** Prebuilt `trust` binaries (cargo-dist, Homebrew), @@ -33,17 +33,14 @@ Rust core. It will be renamed to `trustgraph/trustgraph`. anywhere (GitHub Pages, any static host). `trust follow ` and `trust pull` fetch other people's feeds. This gives a working network with no servers to run. -4. **Holochain.** Read and write atoms on a live conductor using the - `trustgraph-holochain` zome (moved into `holochain/` in Phase 0). The - link-tag codec is already done. -5. **Friendlier UX.** Interactive `trust rate`, readable table output, and +4. **Friendlier UX.** Interactive `trust rate`, readable table output, and `trust lens --format dot|mermaid` to draw your graph. -6. **Harden.** Revoking and updating ratings, key rotation, Sybil-resistance +5. **Harden.** Revoking and updating ratings, key rotation, Sybil-resistance research for the lens, and performance beyond 100k atoms. **Decisions I need from you** (details in [Open decisions](#open-decisions)): -- **Value range:** [PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11) uses `-1..=1` (from Holochain), but trustgraph.net +- **Value range:** [PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11) uses `-1..=1` (negative values express distrust), but trustgraph.net and the protocol README say `0..1`. Confirm, and I'll update those docs. - **Domain for schemas:** is `https://trustgraph.net/ns/v1` OK for the JSON-LD context? @@ -70,8 +67,6 @@ Everything below this line is supporting detail. - **Prior art** in the `trustgraph` org: - [`trustgraph/trustgraph`](https://github.com/trustgraph/trustgraph): the protocol README (Trust Atoms, signed claims, multihash IDs). - - [`trustgraph/trustgraph-holochain`](https://github.com/trustgraph/trustgraph-holochain): - atoms stored as Holochain links (`Ŧ→content\0value\0bucket\0extra`). - [`trustgraph/js-trustgraph-cli`](https://github.com/trustgraph/js-trustgraph-cli) (archived): `trust claim`, `trust get`, `trust map`. - [`trustgraph/trustgraph-schema`](https://github.com/trustgraph/trustgraph-schema): @@ -87,10 +82,9 @@ Everything below this line is supporting detail. |---|---| | Workspace: protocol library + `trust` binary ([PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11)) | ✅ | | Trust Atoms, validation, canonical JSON (RFC 8785), `Qm…` content IDs | ✅ | -| Values: exact decimals in `-1..=1`, Holochain-compatible normalization | ✅ | +| Values: exact decimals in `-1..=1`, rounded to nine significant figures | ✅ | | `did:key` Ed25519 identities, keystore (`0600`) | ✅ | | W3C VC 2.0 + `eddsa-jcs-2022` sign/verify (passes the spec's test vectors) | ✅ | -| Holochain link-tag encode/decode | ✅ | | Local append-only store, verified on the way in | ✅ | | Agent Lens / Trust Cascade, topic filters, rollups | ✅ | | CI (3 OSes, MSRV, clippy pedantic, rustdoc), Dependabot, Apache-2.0 | ✅ | @@ -108,7 +102,7 @@ Everything below this line is supporting detail. 2. **One pure core, thin wrappers.** All protocol logic lives in `trustgraph-core`, which does no I/O (no files, network, clock or randomness). The CLI, WebAssembly and Node packages only move data in and - out. Every other component (web, Holochain, CoreNexus, mobile) uses the + out. Every other component (web, CoreNexus, mobile) uses the same code instead of re-implementing the protocol, and no host (Convex included) shapes the core. See [architecture](../architecture.md). 3. **Unix pipes.** JSON/NDJSON in and out, so commands compose: @@ -136,7 +130,6 @@ built on it change together, in one PR and one CI run. |---|---|---| | [`trustgraph/trustgraph`](https://github.com/trustgraph/trustgraph) (protocol README) | `doc/protocol.md`, updated to the current atom and credential formats | Rename the old repo to `trustgraph-protocol-archive` and archive it | | [`trustgraph/trustgraph-schema`](https://github.com/trustgraph/trustgraph-schema) (JSON-LD) | `schema/`, alongside the new v1 context (Phase 1) | Archive; keep GitHub Pages serving the old URL, or redirect it | -| [`trustgraph/trustgraph-holochain`](https://github.com/trustgraph/trustgraph-holochain) (zome) | `holochain/`, its own Cargo workspace (zomes pin `hdk` versions and build for Holochain's WebAssembly target), using `trustgraph-core` for the tag codec | Archive once the zome builds and tests here | | [`trustgraph/js-trustgraph-cli`](https://github.com/trustgraph/js-trustgraph-cli) | Nothing: `trust` replaces it | Already archived | | This repo, `trustgraph-rust-cli` | | Rename to `trustgraph/trustgraph`. GitHub redirects the old URLs | @@ -146,8 +139,8 @@ built on it change together, in one PR and one CI run. packages in `packages/*` (one pnpm workspace), docs in `doc/`. TypeScript calls the core through the WebAssembly or native package and never re-implements protocol logic. -- **Acceptance:** one `cargo test` and one CI run cover the core, the CLI, the - bindings and the Holochain zome; the old repos are archived and point here. +- **Acceptance:** one `cargo test` and one CI run cover everything in the + repo; the old repos are archived and point here. ### 1. Lock the v1 data format @@ -195,19 +188,7 @@ built on it change together, in one PR and one CI run. - **Acceptance:** two machines exchange atoms through GitHub Pages, and each sees the other in `trust lens`. -### 4. Holochain - -- An adapter behind a cargo feature (`--features holochain`) that talks to a - conductor through `holochain_client`: `trust publish --to holochain`, - `trust pull --from holochain`. -- Map `did:key` identities to Holochain agent keys (both are Ed25519). -- Upstream fix: for tiny values, `trustgraph-holochain`'s value strings can - exceed the documented 12-character limit (`-.00000000100000000`). `trust` - falls back to nine decimal places for these; align the zome to match. -- **Acceptance:** an atom created by `trust` round-trips through a real - conductor in an integration test (nix or a container in CI). - -### 5. Friendlier UX +### 4. Friendlier UX - `trust rate`: interactive prompts when stdin is a TTY (the 2022 TODO list's "prompts that enforce things"), using `dialoguer`. @@ -215,7 +196,7 @@ built on it change together, in one PR and one CI run. - `trust lens --format dot|mermaid` to draw your trust graph. - Named contacts (`trust contact add bob did:key:…`) so you don't paste DIDs. -### 6. Harden +### 5. Harden - **Revocation and updates:** a newer atom from the same source replaces an older one (the lens already prefers the latest); add explicit revocation @@ -237,7 +218,7 @@ built on it change together, in one PR and one CI run. | 3 | Package names | crates `trustgraph-core`, `trustgraph-cli` (binary `trust`); npm `@trustgraph/trustgraph`, `@trustgraph/trustgraph-wasm` | | 4 | Public or private npm | Public: Convex installs native packages from npm at deploy time | | 5 | Copyright line in LICENSE | Currently the unfilled Apache template; e.g. "Trust Graph contributors" | -| 6 | Sharing transport order | HTTPS feeds first (no servers), then Holochain | +| 6 | Sharing transport | HTTPS feeds first (no servers to run); add other transports only when there is demand | | 7 | MSRV policy | Stable minus about 6 releases; raise it on purpose, never by accident | | 8 | The existing `trustgraph/trustgraph` repo | Move its README into `doc/protocol.md`, rename it `trustgraph-protocol-archive`, archive it, then rename this repo to `trustgraph/trustgraph` | @@ -248,7 +229,7 @@ From `src/main.rs` (September 2022): | 2022 TODO | Status | |---|---| | decide on some initial use cases | ✅ rate, sign, verify, store, query, lens ([PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11)) | -| make ArgGroup, make prompts that enforce things | ✅ validation in [PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11); interactive prompts in Phase 5 | +| make ArgGroup, make prompts that enforce things | ✅ validation in [PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11); interactive prompts in Phase 4 | | call an API? write to trustgraph right now? | Phases 2 and 3 | | what is the interface between CLI and backend? is there a backend? | ✅ The library is the interface; backends are optional plug-ins | | spit out jsonld and optionally pipe to storages | ✅ VC 2.0 JSON-LD on stdout; `trust add` stores it | From 06ecf0d19a6da0b067d024aace20691b971864fc Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 7 Oct 2026 15:29:56 +0000 Subject: [PATCH 09/10] Roadmap: randomness is an opt-in core feature Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UdKneRqUnsbv1t7NyvcT68 --- doc/plan/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/plan/README.md b/doc/plan/README.md index 2e525d4..679dee0 100644 --- a/doc/plan/README.md +++ b/doc/plan/README.md @@ -100,8 +100,9 @@ Everything below this line is supporting detail. monorepo. Protocol logic is Rust; TypeScript is welcome where it fits (web, Convex, extensions) but always calls the core rather than re-implementing it. 2. **One pure core, thin wrappers.** All protocol logic lives in - `trustgraph-core`, which does no I/O (no files, network, clock or - randomness). The CLI, WebAssembly and Node packages only move data in and + `trustgraph-core`, which does no I/O (no files, network or clock; + randomness only through the opt-in `random` feature, which the wrappers + turn on). The CLI, WebAssembly and Node packages only move data in and out. Every other component (web, CoreNexus, mobile) uses the same code instead of re-implementing the protocol, and no host (Convex included) shapes the core. See [architecture](../architecture.md). From ec6e3d151a64594ce093b5e485e6f00ea04b4d2e Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 7 Oct 2026 15:34:40 +0000 Subject: [PATCH 10/10] Roadmap: reflect the merged monorepo PR and harvest ideas from early drafts Update the TL;DR, shipped table and Phase 0 for PR #15 (merged): monorepo layout, optional randomness, CI. Carry forward three ideas from the 2022-23 drafts #9 and #10: Reputon export (Phase 1), IPFS publishing (Phase 3), and lens value filters plus a per-hop falloff view (Phase 4). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UdKneRqUnsbv1t7NyvcT68 --- doc/plan/README.md | 48 +++++++++++++++++++++++++++++++--------------- 1 file changed, 33 insertions(+), 15 deletions(-) diff --git a/doc/plan/README.md b/doc/plan/README.md index 679dee0..102c5bc 100644 --- a/doc/plan/README.md +++ b/doc/plan/README.md @@ -5,26 +5,29 @@ **Where we are:** [PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11) turned this repo from a "hello world" scaffold into `trust`, a working CLI and Rust library for the Trust Graph protocol. You can create identities, sign trust ratings as W3C Verifiable Credentials, store -them, and explore them through your **Agent Lens**. [PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15) then split it into -**one pure Rust core with three thin wrappers**: the `trust` CLI, a -WebAssembly package (browsers, Workers, Convex queries) and a native Node -module (Node, Convex Node actions). See [architecture](../architecture.md). +them, and explore them through your **Agent Lens**. [PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15) then made the repo +the **Trust Graph monorepo**, built on **one pure Rust core with three thin +wrappers**: the `trust` CLI, a WebAssembly package (browsers, Workers, Convex +queries) and a native Node module (Node, Convex Node actions). See +[architecture](../architecture.md). **What's missing:** nothing is published yet, and atoms only live where you put them. The next big steps are **publishing the packages** so CoreNexus and others can use them, then **sharing** atoms between people. **This repo is the Trust Graph monorepo.** Every Trust Graph project lives -here: Rust first, TypeScript where it fits, with all protocol logic in one -Rust core. It will be renamed to `trustgraph/trustgraph`. +here: Rust crates in `crates/*`, TypeScript packages in `packages/*` (pnpm), +with all protocol logic in one Rust core. It will be renamed to +`trustgraph/trustgraph`. **Next steps, in order:** -0. **Become the monorepo.** Bring in the protocol docs and the JSON-LD schema - from their separate repos, archive the old ones, and rename this repo to - `trustgraph/trustgraph`. +0. **Finish the monorepo.** The layout is done. Still to do: bring in the + protocol docs and the JSON-LD schema from their separate repos, archive + the old ones, and rename this repo to `trustgraph/trustgraph`. 1. **Lock the data format.** Publish the JSON-LD context and JSON Schema at - `trustgraph.net`, and freeze the atom and credential shapes as v1. + `trustgraph.net`, freeze the atom and credential shapes as v1, and add + exports to other reputation formats (IETF Reputons). 2. **Release and publish.** Prebuilt `trust` binaries (cargo-dist, Homebrew), the npm packages (`@trustgraph/trustgraph` per-platform via napi-rs, and `@trustgraph/trustgraph-wasm`), and the crates. Prove the WebAssembly @@ -71,6 +74,11 @@ Everything below this line is supporting detail. (archived): `trust claim`, `trust get`, `trust map`. - [`trustgraph/trustgraph-schema`](https://github.com/trustgraph/trustgraph-schema): the 2017 `TrustClaim.jsonld` context. +- **Early drafts** [#9](https://github.com/trustgraph/trustgraph-rust-cli/pull/9) and [#10](https://github.com/trustgraph/trustgraph-rust-cli/pull/10) (2022–23) sketched `trust claim` and + `trust graph` argument parsing. The code is superseded by `trust`, but three + ideas carry forward: exports to other formats (IETF Reputons, Phase 1), + IPFS as a publishing target (Phase 3), and value filters plus a per-hop + "falloff" view for the lens (Phase 4). - **trustgraph.net** and the [FOSDEM 2022 talk](https://archive.fosdem.org/2022/schedule/event/trustgraphs/) describe Agents, the **Agent Lens**, the **Trust Cascade**, and trust @@ -87,12 +95,15 @@ Everything below this line is supporting detail. | W3C VC 2.0 + `eddsa-jcs-2022` sign/verify (passes the spec's test vectors) | ✅ | | Local append-only store, verified on the way in | ✅ | | Agent Lens / Trust Cascade, topic filters, rollups | ✅ | -| CI (3 OSes, MSRV, clippy pedantic, rustdoc), Dependabot, Apache-2.0 | ✅ | +| CI (3 OSes, MSRV, clippy pedantic, rustdoc), Dependabot, Apache-2.0 ([PR #11](https://github.com/trustgraph/trustgraph-rust-cli/pull/11)) | ✅ | | Pure `trustgraph-core` (no I/O, enforced in CI) + shared JSON `api` ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ | -| `@trustgraph/trustgraph-wasm`: web and Node builds, 547 KiB ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ built and tested, not published | +| Monorepo: Cargo workspace (`crates/*`), pnpm workspace (`packages/*`), Rust-first language policy ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ | +| Optional `random` feature: `Keypair::generate` / `generateKeypair()`, off in the core by default ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ | +| `@trustgraph/trustgraph-wasm`: web and Node builds, 540 KiB ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ built and tested, not published | | `@trustgraph/trustgraph`: napi-rs, tested on Linux, macOS, Windows ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ built and tested, not published | | Shared TypeScript types; one smoke test across all JS builds ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ | | `lens` on 100k atoms (Node 24 LTS): 0.54 s WebAssembly, 0.43 s native ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ | +| CI: purity check, WebAssembly size budget, native addon on 3 OSes, latest Node LTS plus Node 22 ([PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15)) | ✅ | ## Design principles @@ -122,10 +133,11 @@ Everything below this line is supporting detail. Each phase is a few small PRs, and is done only when its acceptance criteria pass in CI. -### 0. Become the monorepo +### 0. Finish the monorepo One repository for every Trust Graph project, so the core and everything -built on it change together, in one PR and one CI run. +built on it change together, in one PR and one CI run. The layout and +language policy shipped in [PR #15](https://github.com/trustgraph/trustgraph-rust-cli/pull/15); what remains is bringing the other repos in. | Today | Moves to | Then | |---|---|---| @@ -136,7 +148,7 @@ built on it change together, in one PR and one CI run. - Import with history (`git subtree add` or `git filter-repo`), so blame and past discussion survive. -- Layout rules: Rust crates in `crates/*` (one Cargo workspace), TypeScript +- Layout (done): Rust crates in `crates/*` (one Cargo workspace), TypeScript packages in `packages/*` (one pnpm workspace), docs in `doc/`. TypeScript calls the core through the WebAssembly or native package and never re-implements protocol logic. @@ -152,6 +164,8 @@ built on it change together, in one PR and one CI run. decided value range. - Add golden files of real atoms and credentials to the repo; CI fails if the bytes ever change. +- `trust convert --to reputon`: export atoms as IETF Reputons (RFC 7071), so + existing reputation systems can read them (an idea from the early drafts). - **Acceptance:** an off-the-shelf VC library (e.g. Digital Bazaar's `@digitalbazaar/vc` with the `eddsa-jcs-2022` suite) verifies a credential signed by `trust`. @@ -186,6 +200,8 @@ built on it change together, in one PR and one CI run. verify every atom before storing it. Use ETags so repeat pulls are cheap. - Optional discovery via `/.well-known/trust/atoms.ndjson`, plus `did:web` so an organization can sign with its own domain. +- Next transport, if there is demand: IPFS (`trust publish --to ipfs`). Atom + IDs are already SHA2-256 multihashes, the same as IPFS's. - **Acceptance:** two machines exchange atoms through GitHub Pages, and each sees the other in `trust lens`. @@ -195,6 +211,8 @@ built on it change together, in one PR and one CI run. "prompts that enforce things"), using `dialoguer`. - `--format table` for humans; JSON stays the default when piped. - `trust lens --format dot|mermaid` to draw your trust graph. +- `trust lens --min-value / --max-value` filters, and `--explain` to show how + much trust each hop passed along (the "falloff" idea from the early drafts). - Named contacts (`trust contact add bob did:key:…`) so you don't paste DIDs. ### 5. Harden