lib

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

README.md (16405B)


      1 # Radroots execution
      2 
      3 Typed command execution and recovery boundaries. The current implementation
      4 contains allocation-free errors with canonical codes, fixed diagnostic enums,
      5 four explicit retry classes and a validated operation/admission relationship.
      6 The default package supports native Rust and `no_std` targets without a runtime.
      7 The optional `session` feature adds host resource ownership without creating
      8 an async runtime or detached tasks. Native handles and futures are thread safe;
      9 WASM handles use `Rc` and accept thread-local host futures.
     10 
     11 The optional `signer_session` feature owns a provider together with its scoped
     12 host callbacks. Construction is inert. Explicit observation freezes the first
     13 participant key and rejects later identity drift; cached capabilities supply
     14 no workspace grant or stock authority. Close stops admission, quiesces callback
     15 dispatch, drains observations, awaits host disposal and releases roots. Failed
     16 or cancelled disposal must be resumed. The Client must retain this scope before
     17 awaiting first observation, including when attachment fails or loses its waiter.
     18 
     19 The optional `client_session` feature composes this scope with an actual
     20 `SessionHost`. Attachment is retained before its first await, including before
     21 worker startup. Quiesce permanently stops admission and host callback dispatch;
     22 the owner then drains work, disconnects transports, disposes callbacks and closes
     23 storage. A failed or cancelled attachment remains reachable for explicit cleanup.
     24 No lifecycle observation authenticates a workspace or admits a command.
     25 
     26 A proposed operation ID is not durable admission. Unknown signing or commit
     27 outcomes keep the original identity and require exact-operation continuation
     28 or manual reconciliation. Uncertain initial admission remains explicitly
     29 `Admission::Unknown`; it is neither confirmed admission nor known failure.
     30 Signing and delivery results require confirmed durable preparation.
     31 Same-operation continuation means
     32 resuming or querying retained state; it never authorizes fresh preparation or
     33 blind signing. An executor may construct a retained report only after its
     34 actual durable store confirms admission. This reporting value grants no
     35 authority and performs no transaction.
     36 
     37 ```rust
     38 use radroots_domain::OperationId;
     39 use radroots_execution::{Admission, Code, Error, OperationContext, RetryClass};
     40 
     41 let operation = OperationId::from_bytes([7; 32]);
     42 let error = Error::new(
     43     Code::InvalidInput,
     44     OperationContext::proposed(Some(operation)),
     45     RetryClass::Never,
     46     None,
     47 )?;
     48 assert_eq!(error.context().operation_id(), Some(operation));
     49 assert_eq!(error.context().admission(), Admission::NotAdmitted);
     50 # Ok::<(), radroots_execution::InvalidErrorContext>(())
     51 ```
     52 
     53 Details accept fixed field/reason categories, never private payloads, paths or
     54 backend prose. Display contains only a canonical code and fixed message;
     55 errors have no retained underlying cause. Bindings must preserve the typed
     56 operation ID and explicit admission/retry disposition.
     57 
     58 ```compile_fail
     59 use radroots_execution::{Detail, Field};
     60 
     61 let _ = Detail::new(Field::Signer, String::from("private signer response"));
     62 ```
     63 
     64 ```compile_fail
     65 use radroots_execution::{Code, Error, RetryClass};
     66 
     67 let _ = Error {
     68     code: Code::CommitUnknown,
     69     retry: RetryClass::Never,
     70 };
     71 ```
     72 
     73 With `session`, `Session::new` takes explicit resources and a nonzero in-flight
     74 limit. Construction performs no work. Awaiting `start` starts the host's bounded
     75 workers; only successful startup enables resource admission. Cloned handles
     76 share the same gate. `WorkPermit` retains resources and capacity for owned
     77 executor work, independently of its caller's observation. It is not durable
     78 command admission. Executors must retain it through result/uncertainty storage.
     79 
     80 On its first poll, `close` permanently closes admission and interrupts pending
     81 startup. It then quiesces workers, drains permits, disconnects transports/auth,
     82 disposes callbacks and closes storage last. Successful shutdown stages are
     83 retained across cancellation or known failure. Awaiting close again resumes the
     84 unfinished host hook. Hosts must independently preserve their own partial hook
     85 progress and obtained results. Dropping an unpolled close performs no shutdown;
     86 dropping handles or permits never claims durable completion.
     87 
     88 With `workspace_session`, explicit attachment authenticates a protected
     89 credential through the selected host. `WorkspaceSession::command_context`
     90 purely freezes the captured attachment and all explicit context fields without
     91 I/O or a clock read. Current grant, revision and expiry require revalidation.
     92 The opaque `CommandContext` has no public field constructor or JSON deserializer.
     93 Closing the attachment invalidates its contexts. A custom adapter is an explicit
     94 host trust boundary and requires its own qualification; its observation cannot
     95 establish native SQL authority. An approval descriptor is not consent proof.
     96 
     97 `ClientSession::inquire` and `publish_listing` capture a validated command from this client's own
     98 authenticated context, calls the actual journal admission and queries its
     99 coherent retained graph. It does not preempt original-operation lookup with a
    100 fresh deadline check. Known failure, uncertain initial commit and a failure
    101 after confirmed admission keep distinct original-ID dispositions. T0 itself
    102 performs no signing or network work. An explicitly online `CommandRuntime`
    103 continues accepted work through original planning, exact signing, protected
    104 capture, installation and publication. Public listing work uses public targets
    105 without private routing, encryption or wrapping; private inquiry retains those
    106 requirements. `operation` reads original progress
    107 through an explicitly selected client-owned scope, independently of the old
    108 first-issue deadline. The qualified concrete bounded worker owns accepted native
    109 admission through observer loss; its close must drain accepted work.
    110 
    111 `ClientSession` routes explicit private inventory creation, corrections, mapping,
    112 original-effect reads and proven-unissued cleanup through the supplied inventory
    113 port and this client's exact owned attachment. These calls require a bounded
    114 `TaskHost`; no inline fallback starts them. The existing resource permit and live
    115 byte reservation move into each accepted task until the store settles, including
    116 after observer loss. Close drains these tasks before disposal. The concrete store
    117 must still authenticate current scope, independently retained minima and actual
    118 protected effects. A custom port or a missing query result proves no authority,
    119 safe nonissuance or commit. These paths construct no signer or transport.
    120 An accepted admission task lost before replying reports unknown initial admission
    121 with its original operation ID and manual reconciliation, never known failure.
    122 
    123 Package upload is not authorized. Full commerce authority, complete listing revision
    124 behavior, final browser qualification and new bindings remain separate
    125 requirements. Revalidating a context is not durable admission;
    126 the authoritative transaction must recheck its scope.
    127 
    128 
    129 `OperationReceipt<T>` owns the original captured scope, command and transaction
    130 identities, issuance window, authority checkpoint and coherent progress digest.
    131 It separates installation, per-recipient issuance, delivery and caller waiting.
    132 Its diagnostics contain no private command text or ciphertext. The optional
    133 `receipts` feature projects a Storage operation snapshot without I/O; the
    134 concrete adapter must qualify the underlying authenticated coherent query.
    135 The native T2 profile projects an owned bounded `ChatMessage` or `Listing` when
    136 the concrete owner reports the matching installed result. `OperationStatus`
    137 uses an explicit `OperationValue`; a public listing never projects as a message.
    138 It preserves the original installation
    139 transaction/time separately from later recipient publication-work transactions.
    140 Pending wrapping/publication work does not establish transport acknowledgement.
    141 Newly captured recipient evidence may require T2 continuation while the original
    142 message remains installed; unknown issuance remains independently unknown.
    143 Expired remaining first issuance is blocked while obtained and unknown facts
    144 remain retained. Changing a wait observation cannot change those facts.
    145 Default receipt values remain usable without an async runtime on noStd targets;
    146 the Storage-backed projection is a separately selected host feature.
    147 
    148 The D projection retains original outer/target intent summaries and independent
    149 target observations, including the full request ID, target fingerprint and
    150 endpoint attempt number. Unobserved retained potential invocations remain
    151 unknown; observed rejection or timeout does not become acceptance. Accepted
    152 evidence is evaluated with the shared original target policy, independently for
    153 each publication work item and across its independently selected retries,
    154 without erasing another recipient's pending state or weakening the full policy.
    155 These projections perform no transport or participant signer invocation and
    156 never renew a scheduling lease.
    157 
    158 `ClientSession::prepare_stock_acceptance` captures the existing seller command
    159 from its exact client-owned scope and preserves the supplied independent stock,
    160 private-source and listing minima. The bounded target task retains captured
    161 inputs, proof, resource permit and byte reservation through store settlement
    162 after observer loss; close drains accepted work. Missing or refused task hosts
    163 execute no fallback. Loss of an accepted admission task preserves the original
    164 ID with unknown T0 and manual reconciliation. The result is preparation only;
    165 the concrete store still authenticates consent and actual atomic holds. This
    166 low-level method does not supply complete ordinary commerce orchestration.
    167 
    168 `SignerSession::recover_exact` uses the already attached frozen identity and
    169 rechecks the actual recovery capability before calling the qualified method.
    170 Unobserved, unavailable, closed or changed scopes return original-bound
    171 indeterminate state without legacy or first-signing fallback. Active calls retain
    172 the provider and callback scope until settlement; close waits for those calls.
    173 Foreign callback bindings are rejected with bounded forensic identity. Correctly
    174 bound obtained bytes and nullable observation survive unchanged. The composing
    175 executor must still own the complete task and durable capture, authenticate the
    176 original store claim and enforce retained replay policy. This scope grants no
    177 stock authority, renewed deadline or proof of original nonissuance.
    178 
    179 `ClientSession::capture_stock_evidence` owns a bounded copy of borrowed original
    180 evidence through the selected shared port. Accepted tasks outlive their caller's
    181 wait. Errors, unknown appends and mismatched receipts retain exact bytes, original
    182 credentials and resource/byte leases. A real storage failure keeps its error code
    183 and requires manual reconciliation. `drain_stock_evidence` retries that same
    184 material; it performs no signing, T0, installation or delivery. Close drains the
    185 owner before callback/key/storage disposal and remains resumable on failure.
    186 Fresh inventory preparation/mutation and new command first-signature calls
    187 refuse while material remains unpersisted; independent reads remain available.
    188 Borrowed originals survive unsupported/refused hosts. Scope checks preserve the
    189 immutable namespace and actor; host observation metadata supplies no permission
    190 or renewed issuance window. Matching host reports remain a trust boundary, not
    191 cryptographic transaction proofs. Full ordinary commerce orchestration is a
    192 separate requirement.
    193 
    194 Capture drain calls explicit `InventoryStore::reconcile_stock_evidence`; a blind
    195 append retry cannot resolve a concrete host's uncertain connection. The qualified
    196 native host retains writer ownership while authenticating and reopening that
    197 same namespace. Core keeps the original material and leases until a matching
    198 confirmed result, including through a refused preflight or lost observer.
    199 
    200 With `commerce`, `SignerSession::verify_commerce_plan` qualifies the complete
    201 original plan through the attached provider's frozen observed identity and
    202 existing per-call admission. Changed identity latches a refusal, and missing
    203 capabilities or a closing scope cannot confirm a plan. Active decryption retains
    204 provider/callback roots until settlement; each observation and decryption uses
    205 the existing single-call capacity. No legacy or first-signing method is invoked.
    206 The shared Signing proof preserves original bytes and deadline without granting
    207 T1 or stock authority. The composing executor still owns the complete task and
    208 subsequent durable boundaries after caller cancellation.
    209 
    210 `ClientSession::accept_stock_order` owns captured acceptance through actual T0,
    211 complete original peer/self route and encryption checks, T1, confirmed claims,
    212 exact scoped signing, retained S and initial T2. The shared `CommandRuntime`
    213 contains this algorithm; `session::commerce::AcceptanceStore` supplies typed
    214 target transactions and authenticated read-only snapshots. Host adapters select
    215 no new business inputs or policy. Native facade views use the same configured
    216 owner as inventory, with no second database or executor.
    217 
    218 The peer commitment runs first and confirmed peer S installs the agreement
    219 before self-history work. Missing IO or signing leaves explicit pending facts.
    220 `resume_stock_acceptance` uses only original inputs; existing non-replayable
    221 claims never obtain a first-dispatch permit, and qualified local recovery needs
    222 both retained policy and a current concrete permit. Obtained bytes enter the
    223 retained evidence owner before persistence. Verified signer bytes enter that
    224 owner before fallible request conversion; conversion refusal retains exact bytes,
    225 credentials and the original byte lease. Accepted tasks outlive caller waits,
    226 and close retains callback roots through settlement and durable capture. Query
    227 facts keep preparation, recipient evidence, installation and actual abort
    228 separate. This path performs no outer wrapping, relay publication, stock release
    229 or proof of original nonissuance; full commerce/accounting closure remains open.
    230 
    231 Observed rejected signer output returns `SignerTampering` with the original
    232 confirmed operation identity. Effectful commands return `ExecutionResult`;
    233 its allocation-free Copy `ExecutionFailure` retains the compact primitive Error
    234 plus optional fixed Signing rejection through `signer_rejection()`, including
    235 exact prefix coverage. The primitive Error keeps its 64-byte budget and the
    236 separate command failure is bounded to 128 bytes; neither
    237 failure type owns an untrusted raw payload. Ordinary acceptance
    238 and the generic chat/listing loop stop further issuance on rejection. Already
    239 captured peer evidence remains retained and matching installation completes
    240 before reporting a self-copy rejection. A later installation failure preserves
    241 its actual error code together with signer diagnostics and manual recovery.
    242 Unknown installation stops delivery. These diagnostics are caller observations,
    243 not durable forensic records, authenticated business output or proof that the
    244 original signer never issued. Missing/unsupported/uncertain outcomes keep their
    245 existing conservative claims; no rejection authorizes another first dispatch,
    246 stock release or renewed deadline.
    247 
    248 Generic chat/listing execution registers the original obtained artifact and
    249 attempt with prepared capture credentials and its resource lease before
    250 fallible storage conversion. Conversion or append failure retains the original
    251 bytes, blocks further issuance and permits only original capture reconciliation.
    252 `CommandRuntime::drain` returns the compact execution `Error`, preserving the
    253 actual store code, original confirmed operation and manual reconciliation
    254 through resume and close, including when another operation encounters that
    255 retained obligation. Observation append failures likewise retain their original
    256 operation. A failed conversion is cached without discarding its signed input;
    257 neither a new caller nor close may relabel it as a successful capture.
    258 
    259 The observed `SignerSession` implements Signing's narrow `ExactIssuer` port
    260 through the existing scoped exact call, preserving actual current identity,
    261 capability, single-call admission, callback lifetime and bound-result checks.
    262 The port itself supplies no fresh claim or durable nonissuance authority.