lib

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

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.