README.md (12168B)
1 # radroots 2 3 `radroots` is the ordinary Rust entry to shared Radroots values and execution. 4 The Client owns one coherent execution session and its actual store. Clones 5 share admission and shutdown. Source is in refactor; package release remains 6 separately governed. 7 8 ## Explicit preview 9 10 The default `client` feature enables an in-memory preview. Construction opens 11 no file, network, keyring, runtime or worker. Its deterministic cache generation 12 is not an operation ID or stock authority. 13 14 ```rust 15 # async fn run() -> radroots::Result<()> { 16 use radroots::{Client, StartMode}; 17 let client = Client::preview(); 18 client.start(StartMode::LocalOnly).await?; 19 client.close().await?; 20 # Ok(()) 21 # } 22 ``` 23 24 With `native`, `Client::open(NativeConfig::public_read(options)).await` opens 25 the actual SQLite cache from explicit validated host paths, mode and source 26 generation. It performs no networking or automatic command replay. This public 27 cache scope does not open an authenticated participant workspace or create 28 seller stock authority. On Unix, explicitly adding an opened protected 29 `NativeWorkspace` with `NativeConfig::with_workspace` enables `Client::attach`. 30 Attachment verifies its persisted credential and exact selection before returning 31 `WorkspaceSession`. That session constructs opaque, immutable command contexts 32 without I/O or a clock read; admission must recheck current rights and expiry. 33 A context does not submit a command or prove 34 user consent. After explicit start, `client.inbox().inquire(context, input)` 35 durably captures a known-kind inquiry through the actual protected journal. 36 Local-only submission returns a coherent receipt for retained preparation; 37 online submission owns continuation through signing, installation and delivery. 38 Each dimension reports its actual independent facts. `client.operations(&scope)` 39 selects an explicitly authenticated attachment for `get(operation_id)` and 40 matching-digest reads. Every call enforces this client's attachment ownership 41 and current persisted grant. An expired retained inquiry remains queryable and 42 replay uses its original transaction, command, correlation and issuance window; 43 new expired input and conflicting reuse are refused. 44 45 The existing bounded native worker owns accepted admission after observer loss; 46 client close drains it before releasing storage. Unpolled calls do nothing. 47 Network pairing, complete seller authority and final browser qualification 48 remain separate requirements. 49 50 `attach_signer` observes the concrete provider only after retaining its callback 51 scope. The first successful key freezes and later drift invalidates that scope. 52 Observation grants no workspace, command or stock authority. Failed/cancelled 53 attachment remains reachable through `signer_session` for explicit cleanup. 54 55 Close permanently stops admission, quiesces callback dispatch, drains work, 56 disconnects owned transports, disposes callbacks and closes storage last. Failed 57 or cancelled close retains its unfinished stage; await close again. An unpolled 58 future has no shutdown effect, and Drop supplies no completion receipt. 59 `CloseReceipt` reports actual resource closure, never business installation. 60 Native handles/futures retain thread guarantees; shared browser resource code 61 uses local handles/futures. Compilation does not qualify browser runtime hosts. 62 63 Errors come from `radroots_execution`: fixed codes, bounded redacted details, 64 explicit admission/retry disposition and optional exact operation identity. 65 Backend prose, private payloads and paths are not retained in the error. 66 67 ## Native inquiries 68 69 An explicitly opened protected workspace can be supplied with 70 `NativeConfig::with_workspace`. Attach its authenticated scope and a scoped 71 participant signer to the Client. `with_nostr` additionally selects exact relay 72 destinations, directional access and a relay-acceptance criterion. 73 `StartMode::Online` permits command IO without querying or replaying on startup; 74 `LocalOnly` keeps commands at durable admission without network or signing. 75 A started session cannot silently escalate from local to online mode. 76 77 `client.inbox().inquire(context, input)` owns accepted native work through 78 planning, exact participant signing, protected capture, logical installation 79 and retained-envelope publication. Peer and self copies have independent 80 progress. Relay acceptance proves neither recipient delivery nor acceptance 81 of an agreement. Original operation queries never dispatch work. 82 `client.operations(&scope).resume(operation, digest)` explicitly continues an 83 original inquiry: retained signing claims cannot be reissued, and publication 84 retries preserve exact original bytes, the full criterion and prior accepted 85 targets. A dropped observer does not cancel the native job. Obtained material 86 whose capture fails stays owned; close reports recovery until its protected 87 capture can be confirmed. 88 89 ## Native initial listings 90 91 `client.listings().publish(context, input)` uses the same owned command runtime 92 and protected journal for an authenticated seller's initial public listing. 93 Its `OperationReceipt<domain::Listing>` contains a business result only after 94 actual installation. Text and exact terms come from the captured command; 95 author, revision and event time come from its retained public signing plan and 96 obtained evidence. An existing coordinate cannot be replaced by publishing it 97 again. Revision editing, pause/withdraw and full stock commitments remain separate requirements. 98 99 Public planning uses the configured public relay targets and exact-event 100 signing. It performs no private-route query, encryption or wrapping. Delivery 101 sends the original signed event. Scoped queries and explicit resume return 102 `OperationStatus`, whose `OperationValue` distinguishes Listing from Chat. 103 Reopening, reading and command replay do not redispatch retained work; explicit 104 resume preserves the original bytes, criterion, targets and retry budget. 105 106 ## Values and retained capabilities 107 108 `client.stock(&scope)` selects this client's authenticated attachment for private 109 pool creation, exact available-stock adjustment/spoilage, private option mapping, 110 pool/mapping reads and original-effect recovery. Inputs are typed; each call 111 requires an independently retained inventory minimum. The native configuration 112 retains journal and inventory views of the same explicitly opened workspace, 113 and close drains the same bounded task owner before closing that workspace. 114 Public-cache and preview construction cannot adopt a foreign stock attachment. 115 An ordinary outbox cannot become a stock owner through these calls. 116 117 `client.operations(&scope).abort_proven_unissued(minimum, operation, digest)` 118 explicitly requests the store's proven original-preparation cleanup; its selectors 119 assert no nonissuance proof. `preparation_abort` reads the original result and 120 absence authorizes nothing. Claims and unknown issuance remain nonspendable. 121 These calls neither sign nor publish, and cleanup is separate from business 122 cancellation or stopping delivery. Full commerce orchestration, qualified claimed 123 attempt reconciliation and the final common receipt/binding surface remain open. 124 125 `client.orders(&scope).accept(context, minimum, sources, listings, input)` owns 126 the captured acceptance through the same native stock owner's T0/T1/S and 127 initial T2. Core verifies the complete original peer/self routes and ciphertexts 128 before signing, captures peer evidence and installs its agreement before 129 self-copy work. Inspect `AcceptanceStatus` for independent recipient and 130 installation facts. Preparation alone is pending; this path claims no wrapping 131 or relay delivery. `acceptance_status` reads original facts and 132 `resume_acceptance` explicitly continues original retained work. Existing claims 133 never provide a fresh signing permit. Qualified recovery requires the retained 134 policy, actual current host permit and original window. Caller wait loss cannot 135 discard accepted work or obtained material. Application migrations, full order 136 transitions/accounting, original negative reconciliation and final qualification 137 remain separate required work. 138 139 Effectful commands return `ExecutionResult` with a bounded allocation-free 140 `ExecutionFailure`; resource and query errors keep the compact `Error`. 141 Rejected signer callbacks return `SignerTampering` and bounded original 142 `error.signer_rejection()` metadata. This contains a fixed reason and optional 143 digest with its actual coverage, with no raw signer payload. Inspect the original 144 operation separately: a peer commitment may already be installed while self 145 history remains unresolved. A later storage failure retains its actual code and 146 the same signer diagnostic. Rejection is no original nonissuance or stock-release 147 proof, and caller diagnostics are not durable forensic storage. 148 149 `radroots::domain` provides exact decimals and distinct order, thread, workspace, 150 executor and operation identities. `radroots::OperationId` is the 256-bit 151 retained identity. These values alone perform no authorization or transaction. 152 153 Farm, listing, trade, event, identity, transport, geographic and knowledge 154 modules retain their source-owned values/planners and advanced capability 155 paths. The advanced `radroots_sdk` retains its existing explicit transport 156 composition. The ordinary Client composes the shared execution owner directly. 157 Optional capabilities remain governed by their actual host/target 158 qualification and do not become available because a feature compiles. 159 160 The former root `ClientBuilder` and builder-returning memory/native helpers 161 are replaced by explicit Client preview/open methods. Advanced SDK callers 162 remain at their owning package. No wildcard or SDK namespace is exposed: 163 164 ```compile_fail 165 use radroots::sdk; 166 ``` 167 168 ```compile_fail 169 use radroots::ClientBuilder; 170 ``` 171 172 The reviewed Rust API lives in 173 [`contracts/api_baselines/radroots.txt`](../../contracts/api_baselines/radroots.txt). 174 The approved successor ownership and host contracts live in 175 [`shared_sdk_refactor.v1.json`](../../contracts/architecture/decisions/shared_sdk_refactor.v1.json). 176 177 178 The common `OperationReceipt<T>` types are exported by this facade. Their owned 179 observations preserve original identities and independent issuance, installation, 180 delivery and caller-wait dimensions. The advanced native journal can supply a 181 coherent retained snapshot for this projection. Native T2 can install a bounded 182 logical chat result and retain independent recipient publication work; its 183 original installation time/transaction remain separate from later work and 184 unknown issuance. `domain::ChatMessage` is the owned private business view. 185 The ordinary native inquiry and initial-listing boundaries continue accepted 186 online work through exact signing, protected capture, installation and delivery. 187 Full commerce behavior, final cross-platform acceptance and generated binding 188 qualification remain separate requirements. 189 190 `client.stock(scope).capture_evidence(&request)` sends obtained original evidence 191 to that client's selected shared stock store through Core's bounded task owner. 192 The original request remains borrowed; failed or unknown captures stay owned 193 after observer loss. `drain_evidence` retries this client's retained originals 194 without signing or changing captured bytes. Close preserves unresolved material 195 and resource ownership before disposing callbacks, keys or storage. The concrete 196 qualified store still authenticates the actual protected claim and exact signed 197 bytes; input and receipt metadata grant no authority. This low-level capture 198 surface supplies neither full commerce execution nor original nonissuance proof. 199 200 Original acceptance dispatch is consumed by the selected native host, which owns 201 its one exact issuer invocation. An original pre-dispatch refusal is retained by 202 the client before storage capture, survives a lost caller or failed append, and 203 joins explicit evidence drain and close retry. Coherent recipient status retains 204 that authenticated original fact separately from any later valid signature. 205 Recovery refusals never become original observations. These facts do not release 206 stock or qualify arbitrary adapters; claimed-abort handling and full commerce 207 accounting remain in implementation.