lib

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

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.