Trust Graph monorepo: pure Rust core with CLI, WebAssembly and Node wrappers

[harlantwood]

Summary

This makes the repo the Trust Graph monorepo: Rust first, TypeScript where it fits. Inside it is one pure Rust core with three thin wrappers, so Convex is just another caller. Full write-up: doc/architecture.md.

crates/                 Cargo workspace (crates/*)
├── trustgraph-core     pure Rust: no I/O, no async runtime, data in → data out
├── trustgraph-cli      `trust` binary
├── trustgraph-wasm     @trustgraph/trustgraph-wasm (wasm-bindgen): browsers, Workers, Deno, Convex queries
└── trustgraph-node     @trustgraph/trustgraph (napi-rs): Node and Convex Node actions
packages/               pnpm workspace (packages/*), for TypeScript projects as they arrive
bindings/               TypeScript types shared by both npm packages

Monorepo

• Cargo workspace: crates/*, so new crates join automatically.
• pnpm workspace: crates/trustgraph-node plus packages/*.
  • One pnpm-lock.yaml, and packageManager: pnpm@12.9.1.
  • Root scripts: build:node, test:node, typecheck.
• Node versions:
  • Development and CI use the latest LTS: .nvmrc is lts/*, which is Node 24 today.
  • Published packages support Node ≥ 22. CI also smoke-tests on Node 22.
• Language policy: protocol logic lives only in trustgraph-core. TypeScript calls the core through the WebAssembly or native package. It never re-implements signing, IDs or scoring.
• README: now the monorepo front page. It covers what's in the repo and where new crates and packages go.

The core never does I/O

• Renamed: trustgraph → trustgraph-core, trust-cli → trustgraph-cli. The binary is still trust.
• Callers pass in timestamps and data. The file-backed Store lives in the CLI. Record and Query stay in the core.
• Randomness is optional: the random cargo feature is off by default and on in all three wrappers.
  • It adds Keypair::generate and generateKeypair(). They use the OS random number generator, or crypto.getRandomValues in WebAssembly.
  • keypairFromSeed still works.
  • generateKeypair is the one non-deterministic function. Call it in a client or action, not inside a reactive query.
• scripts/check-core-purity.sh fails CI if any of these happen:
  • the core's source does I/O outside the feature-gated src/random.rs;
  • that module loses its gate;
  • the default dependencies gain getrandom, rand, tokio, libc or an HTTP client.
• CI also lints the core alone with default features.
• Deterministic otherwise, signatures included.

One API, three wrappers

• trustgraph_core::api is a JSON-shaped API with camelCase names: generateKeypair, keypairFromSeed, parseAtom, atomId, canonicalAtom, toCredential, signAtom, verify, lens, rollup.
  • Every wrapper exposes exactly these, and the CLI calls them too.
• trustgraph-wasm has two builds, both made by scripts/build-wasm-package.sh:
  • web/: initialized from the .wasm bytes with initSync, no fetch.
  • node/: for Node.
• trustgraph-node uses napi-rs with one package per platform, the same pattern as @resvg/resvg-js.
• Shared TypeScript types are in bindings/trustgraph.d.ts, checked with tsc --strict.
• One smoke test, tests/js/smoke.mjs, runs against the native addon and both WebAssembly builds.

CI

• Jobs:
  • lint and purity
  • tests on Linux, macOS and Windows
  • MSRV (1.85)
  • the WebAssembly package: build, smoke tests, tsc, benchmark, and a 1 MiB size budget
  • the native addon on all three OSes, plus Node 22
• actions/checkout v7. This supersedes Dependabot #13.
• Dependabot now ignores dtolnay/rust-toolchain. Its ref is the Rust version under test, which Dependabot misread in #14. Dependabot still covers cargo and npm/pnpm.

Removed

• Holochain support: the link-tag codec, Value::to_holochain_string, and trust convert --to holochain.

Performance (Node 24 LTS, Linux x86-64)

	WebAssembly	Native
Size	540 KiB (226 KiB gzipped)	1.2 MB (Linux x64)
Module load	4.5 ms	2.7 ms
lens, 10k atoms	51 ms	35 ms
lens, 100k atoms	0.54 s	0.43 s

• lens is about 2× faster than on master. It computes each agent's edges once and skips content IDs it doesn't need.
• 100k atoms fits well under Convex's 1 s query limit. Bigger graphs should use rollups precomputed natively or by the CLI.

Still open

1. Public or private npm: Convex's externalPackages installs from npm at deploy time.
2. A real Convex deployment spike: the numbers above come from Node, not Convex.

Test plan

• cargo test --workspace on Rust 1.99 and 1.85 (random on): 64 core unit, 7 property, 3 doctests, 8 CLI unit, 12 CLI end-to-end
• cargo test -p trustgraph-core with default features (no randomness): 61 unit tests
• cargo clippy -D warnings (workspace, core alone, and wasm32-unknown-unknown); cargo doc -D warnings; cargo fmt --check
• scripts/check-core-purity.sh passes. It also fails on a planted std::fs call or a removed feature gate.
• JS smoke test (including generateKeypair) passes on Node 24 against all three builds, and on Node 22 against the native addon
• pnpm install --frozen-lockfile, pnpm run build:node, pnpm run test:node, pnpm run typecheck
• CI green on the latest commit (6b29a20): all 9 jobs

Merge this before #12 (the roadmap), which links to doc/architecture.md.

---

History: this started as the CoreNexus architecture pass (a pure core with wrappers). At your request it grew to cover the monorepo setup, pnpm, the latest Node LTS, removing Holochain and opt-in randomness. Before merging, it also absorbed the two pending Dependabot CI updates.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UdKneRqUnsbv1t7NyvcT68