README.md (4616B)
1 # radroots_sync 2 3 Executor-neutral local-first synchronization orchestration for Radroots. 4 5 The package owns the shared ingest, pull, projection, push, policy, and status 6 boundaries. It does not create an executor, spawn workers, install timers, own 7 process lifecycle, store UI state, or branch on concrete transport adapters. 8 9 `StorageSpaceInsufficient` preserves the storage owner's typed capacity failure. 10 It does not establish rollback or absence of signer or remote effects. Retain 11 the original requests, signed bytes and unresolved receipts, then reconcile 12 existing state before retrying. Sync never frees storage or retries implicitly. 13 14 Ingest performs real event-ID and signature verification before host policy. 15 Contract failure defaults to rejection. A host can explicitly retain such a 16 signed observation through `AdmissionPolicy::contract_failure` for canonical 17 replacement evidence; its closed decision permits only rejection or verified 18 retention, never visibility. Invalid IDs and signatures cannot reach this policy. 19 20 Pull receipts retain the last available outcome for each target and bounded 21 cumulative target summaries across returned pages. A later complete outcome 22 does not erase an earlier incomplete or missing outcome. Summaries preserve 23 request order and use the existing 64-target and 1,000-page bounds. A legacy 24 receipt without summaries has unknown cumulative evidence. Even when every 25 page reports completion, callers must inspect pull termination and request 26 scope; a receipt never proves complete global history. 27 28 Publication remains disabled while behavior is implemented and qualified in 29 the subsequent Release V1 sync checkpoints. 30 31 Advanced hosts can call `PushRequest::authored_preparation` with an explicitly 32 captured timestamp to build the same pure preparation used by `prepare_push`. 33 Retain this value when composing a storage draft submission: composite replay 34 compares captured timestamps exactly. Building it performs no storage, signing, 35 clock or network operation. Ordinary preparation identity and replay semantics 36 remain unchanged. 37 38 Prepared signing consumes the authored-evidence signer hook, revalidates its 39 exact request binding, and records verified bytes against the original durable 40 claim even after that claim expires or is superseded. It reloads current state 41 after receipt replay before returning or permitting admission. Caller deadline 42 and cancellation outcomes are reported after retaining valid evidence; stopped 43 work cannot restart admission or signing. An already-signed replay does not 44 require a signer or credentials. The strict expiring authorization hook remains 45 unchanged. 46 47 The host must continue polling an in-flight call to deliver its late evidence. 48 Dropping the future or losing the observation clock leaves the durable attempt 49 unresolved; recovery follows the declared replay capability and never invents 50 a new preimage, event timestamp, or key. Sync creates no worker or timer to 51 retain a discarded future. Delivery-wide stop reconciliation is a separate 52 contract from authored signing evidence. 53 54 Authored delivery retains validated raw results against their original durable 55 claim even after stop, expiry or replacement of that claim. A late callback can 56 change scheduling only under its original still-current lease. Fresh calls 57 reconcile pending facts before any further delivery; reconciliation invokes no 58 transport. Every retry uses the same persisted signed request and target policy. 59 Stop prevents further local work and preserves unknown and accepted effects. 60 61 `PushStatus::delivery_history` exposes consistent bounded claim provenance. 62 Use its explicit no-issued proof and unresolved-history classification together 63 with the plan's cumulative delivery satisfaction and first stop. The existing 64 settlement counters describe scheduling state; they do not prove remote absence. 65 After a post-delivery clock failure, Sync retains the raw non-expiring result 66 with the known pre-effect time as a causal lower bound and returns 67 `ClockUnavailable` without retry scheduling. This is not a measured response 68 time and does not change strict signing or expiring authorization requirements. 69 70 `Engine::deliver_push_selected` accepts an explicit nonempty subset of the 71 frozen delivery targets. It validates the subset before a new claim and passes 72 the original full request to the selected sink boundary. Attempted evidence 73 outside that selection is an invalid adapter contract. Shared claim, stop, 74 late-result persistence, reconciliation and retry semantics remain unchanged; 75 the caller owns eligibility and holds an empty selection without delivery.