README.md (5924B)
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 Host composition uses target-aware shared ownership for storage, signer, 10 transport, clock and identity sources. Native handles retain `Arc` and 11 `Send + Sync`; WASM handles use `Rc` and permit local futures and callbacks. 12 This is a composition contract, not qualification of a browser store/network 13 adapter. The isolated browser-host fixture compiles local interfaces without 14 pulling native SQLite test dependencies into the browser target. 15 16 `StorageSpaceInsufficient` preserves the storage owner's typed capacity failure. 17 It does not establish rollback or absence of signer or remote effects. Retain 18 the original requests, signed bytes and unresolved receipts, then reconcile 19 existing state before retrying. Storage cleanup and future retry scheduling 20 remain host-owned. 21 22 Local authored admission preserves an already stored event's original JSON. 23 After a byte conflict, it reads at most one matching identifier and retries 24 admission once only when the complete signed wire value matches, including 25 signature and extension fields. It verifies that stored value again before 26 advancing admission. The original signing artifact and delivery bytes remain 27 unchanged; identifier equality alone never permits this reconciliation. 28 Both representations must satisfy the duplicate-free, seven-field NIP-01 29 profile with a 64 KiB byte limit. Other storage conflicts retain their 30 existing failure classification. 31 32 Ingest performs real event-ID and signature verification before host policy. 33 Contract failure defaults to rejection. A host can explicitly retain such a 34 signed observation through `AdmissionPolicy::contract_failure` for canonical 35 replacement evidence; its closed decision permits only rejection or verified 36 retention, never visibility. Invalid IDs and signatures cannot reach this policy. 37 38 Projection refresh JSON uses the same checked constructor as native requests. 39 Zero or oversized batch bounds are rejected before storage or reducer work; 40 valid boundary values and the existing wire shape remain unchanged. 41 42 Pull receipts retain the last available outcome for each target and bounded 43 cumulative target summaries across returned pages. A later complete outcome 44 does not erase an earlier incomplete or missing outcome. Summaries preserve 45 request order and use the existing 64-target and 1,000-page bounds. A legacy 46 receipt without summaries has unknown cumulative evidence. Even when every 47 page reports completion, callers must inspect pull termination and request 48 scope; a receipt never proves complete global history. 49 50 Publication remains disabled while behavior is implemented and qualified in 51 the subsequent Release V1 sync checkpoints. 52 53 Advanced hosts can call `PushRequest::authored_preparation` with an explicitly 54 captured timestamp to build the same pure preparation used by `prepare_push`. 55 Retain this value when composing a storage draft submission: composite replay 56 compares captured timestamps exactly. Building it performs no storage, signing, 57 clock or network operation. Ordinary preparation identity and replay semantics 58 remain unchanged. 59 60 Prepared signing consumes the authored-evidence signer hook, revalidates its 61 exact request binding, and records verified bytes against the original durable 62 claim even after that claim expires or is superseded. It reloads current state 63 after receipt replay before returning or permitting admission. Caller deadline 64 and cancellation outcomes are reported after retaining valid evidence; stopped 65 work cannot restart admission or signing. An already-signed replay does not 66 require a signer or credentials. The strict expiring authorization hook remains 67 unchanged. 68 69 The host must continue polling an in-flight call to deliver its late evidence. 70 Dropping the future or losing the observation clock leaves the durable attempt 71 unresolved; recovery follows the declared replay capability and never invents 72 a new preimage, event timestamp, or key. Sync creates no worker or timer to 73 retain a discarded future. Delivery-wide stop reconciliation is a separate 74 contract from authored signing evidence. 75 76 Authored delivery retains validated raw results against their original durable 77 claim even after stop, expiry or replacement of that claim. A late callback can 78 change scheduling only under its original still-current lease. Fresh calls 79 reconcile pending facts before any further delivery; reconciliation invokes no 80 transport. Every retry uses the same persisted signed request and target policy. 81 Stop prevents further local work and preserves unknown and accepted effects. 82 83 `PushStatus::delivery_history` exposes consistent bounded claim provenance. 84 Use its explicit no-issued proof and unresolved-history classification together 85 with the plan's cumulative delivery satisfaction and first stop. The existing 86 settlement counters describe scheduling state; they do not prove remote absence. 87 After a post-delivery clock failure, Sync retains the raw non-expiring result 88 with the known pre-effect time as a causal lower bound and returns 89 `ClockUnavailable` without retry scheduling. This is not a measured response 90 time and does not change strict signing or expiring authorization requirements. 91 92 `Engine::deliver_push_selected` accepts an explicit nonempty subset of the 93 frozen delivery targets. It validates the subset before a new claim and passes 94 the original full request to the selected sink boundary. Attempted evidence 95 outside that selection is an invalid adapter contract. Shared claim, stop, 96 late-result persistence, reconciliation and retry semantics remain unchanged; 97 the caller owns eligibility and holds an empty selection without delivery.