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.