lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

README.md (3841B)

      1 # radroots
      2 
      3 `radroots` is the canonical ordinary-user Rust package for Radroots. It offers
      4 safe local construction, deliberate domain paths, and the common client
      5 boundary without exposing every lower crate or duplicating the advanced SDK
      6 engine.
      7 
      8 The package is enabled for validation-only release qualification. After the
      9 separately approved publication gate, the onboarding command is:
     10 
     11 ```sh
     12 cargo add radroots
     13 ```
     14 
     15 ## Start locally
     16 
     17 The default `client` feature enables deterministic in-process memory storage.
     18 Construction creates no file, contacts no network or daemon, reads no keyring,
     19 installs no runtime or subscriber, and starts no worker. The initial transport
     20 profile is explicitly local-only.
     21 
     22 ```rust
     23 # async fn run() -> radroots::Result<()> {
     24 let client = radroots::client::memory().build()?;
     25 let profile = radroots::client::local_only();
     26 assert!(profile.is_local_only());
     27 
     28 // Clone handles share lifecycle state; shutdown is explicit and asynchronous.
     29 client.close().await?;
     30 # Ok(())
     31 # }
     32 ```
     33 
     34 The default memory generation is process-local and deterministic. Hosts that
     35 persist cursors or compose their own storage generation should use
     36 `radroots_sdk::ClientBuilder` directly.
     37 
     38 ## Product operations
     39 
     40 Farm, listing, and trade writes follow one reliability boundary:
     41 
     42 1. `prepare` validates and freezes a side-effect-free plan.
     43 2. The configured signer authorizes and signs that plan.
     44 3. Enqueue durably accepts it under an operation ID and idempotency key.
     45 4. Delivery runs only for an explicitly selected transport profile.
     46 
     47 Cancellation before durable acceptance makes no commit claim. Cancellation
     48 after acceptance cannot roll back the accepted event; resume with the same
     49 idempotency identity and inspect the canonical receipt. Public event models do
     50 not contain exact farm coordinates, private trade terms, credentials, or key
     51 material.
     52 
     53 Errors expose stable classifications and recovery metadata while retaining
     54 their lower source chain for local diagnostics. Display, debug, diagnostics,
     55 and protocol reports redact bearer credentials and signer material. Canonical
     56 lower crates own serialization and versioned wire contracts; facade aliases
     57 are Rust paths, not a second persistence format.
     58 
     59 ## Features
     60 
     61 | Feature | Behavior |
     62 | --- | --- |
     63 | `client` | safe memory-backed client; the default |
     64 | `native` | explicit SQLite, sync, and local-signing SDK capabilities |
     65 | `blossom` | HTTP-only BUD-11 upload authorization through an opaque host signer |
     66 | `nostr` | explicit Nostr source/sink composition |
     67 | `nip46` | host-owned NIP-46 signer composition; implies `nostr` |
     68 | `radrootsd` | explicitly invoked daemon delivery |
     69 | `geonames` | concrete GeoNames provider capability |
     70 | `knowledge` | canonical knowledge event contracts |
     71 | `full` | the governed complete SDK capability bundle |
     72 
     73 Enabling a feature compiles capability; it never performs I/O. Native storage
     74 opens only through `client::native`, transport is caller-injected, and daemon
     75 delivery happens only when its `deliver` method is invoked.
     76 
     77 ## When to use radroots_sdk
     78 
     79 Use `radroots` for ordinary applications and the primary farm, listing, trade,
     80 identity, event, and transport paths. Use `radroots_sdk` directly when the host
     81 must own source-generation identity, inject arbitrary storage/signing/sync
     82 implementations, coordinate FFI/mobile lifecycle, or inspect advanced
     83 capability and diagnostics contracts. There is intentionally no
     84 `radroots::sdk` namespace or wildcard SDK reexport.
     85 
     86 The namespace separation is a compiled contract:
     87 
     88 ```compile_fail
     89 use radroots::sdk;
     90 ```
     91 
     92 The normative package charter is the [`radroots` release-v1
     93 specification](../../contracts/crates/release_v1/radroots_crates_release_v1.toml).
     94 The reviewed pre-release public API is recorded in the
     95 [`radroots` baseline](../../contracts/api_baselines/radroots.txt).