@derec-alliance/react-native 0.0.6 → 0.0.7

package/README.md

@@ -125,6 +125,27 @@ longer needed (safe to call more than once).
 
 ---
 
+## When `process()` fails
+
+`process()` settles expired deadlines (sharing-round and unpair timeouts)
+before it handles the message, and those are never reported again. So when
+the message then fails, the thrown `DeRecError` carries them: `events` holds
+every event produced before the failure, and `channel_id` names the channel
+the message came from (absent when the bytes were not a decodable envelope).
+Handle the events as you would a successful call's, then the error:
+
+```ts
+try {
+  handle(await protocol.process(bytes));
+} catch (error) {
+  const failure = error as DeRecError;
+  handle(failure.events ?? []);
+  report(failure.channel_id, failure);
+}
+```
+
+---
+
 ## Store interfaces
 
 The application layer owns all persistence; the library never writes to disk
@@ -134,6 +155,9 @@ declared in `src/types.ts`:
 - **`ChannelStore`** — pairing state: helper channels and replica-group
   membership, keyed by `(channelId, replicaId)`.
 - **`ShareStore`** — versioned VSS shares this device holds as a helper.
+  On an owner, `keepList` chooses which versions helpers keep; returning
+  `null` sends no keepList, so helpers keep every version; see
+  [the owner's keep list](https://github.com/derecalliance/lib-derec/tree/main/library#share-store-the-owners-keep-list).
 - **`SecretStore`** — small per-channel key material (shared keys, etc.),
   distinct from share bytes.
 - **`UserSecretStore`** — the most recent user-facing secret snapshot per

package/cpp/Primitives.cpp

@@ -20,6 +20,13 @@ void throwDeRecError(jsi::Runtime& rt, const DeRecError& error) {
 void throwDeRecError(jsi::Runtime& rt,
                      const DeRecError& error,
                      const std::vector<uint8_t>& conflictingChannelIdsJson) {
+  throwDeRecError(rt, error, conflictingChannelIdsJson, {});
+}
+
+void throwDeRecError(jsi::Runtime& rt,
+                     const DeRecError& error,
+                     const std::vector<uint8_t>& conflictingChannelIdsJson,
+                     const ProcessFailureDetails& process) {
   auto names = errorName(error.category, error.code);
   // `message` and `peer_memo` are Rust-owned strings; copy before releasing.
   std::string message =
@@ -53,6 +60,15 @@ void throwDeRecError(jsi::Runtime& rt,
                         jsi::Value::createFromJsonUtf8(rt, conflictingChannelIdsJson.data(),
                                                        conflictingChannelIdsJson.size()));
   }
+  if (process.hasChannelId) {
+    payload.setProperty(rt, "channel_id",
+                        jsi::String::createFromUtf8(rt, std::to_string(process.channelId)));
+  }
+  if (!process.eventsJson.empty()) {
+    payload.setProperty(rt, "events",
+                        jsi::Value::createFromJsonUtf8(rt, process.eventsJson.data(),
+                                                       process.eventsJson.size()));
+  }
   throw jsi::JSError(rt, jsi::Value(rt, payload));
 }
 

package/cpp/Primitives.h

@@ -5,6 +5,7 @@
 
 #include <jsi/jsi.h>
 
+#include <cstdint>
 #include <vector>
 
 extern "C" {
@@ -25,6 +26,22 @@ namespace derec {
                                   const DeRecError& error,
                                   const std::vector<uint8_t>& conflictingChannelIdsJson);
 
+/// What a failed `derec_protocol_process` adds to its error: the events it
+/// produced before failing, and the channel the failing message came from.
+struct ProcessFailureDetails {
+  std::vector<uint8_t> eventsJson;
+  bool hasChannelId = false;
+  uint64_t channelId = 0;
+};
+
+/// As above, additionally attaching `channel_id` (a decimal string) when
+/// `process.hasChannelId` is set, and `events` (the JSON array verbatim)
+/// when `process.eventsJson` is non-empty. Only `process` produces these.
+[[noreturn]] void throwDeRecError(facebook::jsi::Runtime& rt,
+                                  const DeRecError& error,
+                                  const std::vector<uint8_t>& conflictingChannelIdsJson,
+                                  const ProcessFailureDetails& process);
+
 /// Read an `ArrayBuffer` or typed-array argument as a byte range.
 /// Returns `{nullptr, 0}` for `null`/`undefined`.
 struct ByteView {

package/cpp/ProtocolHost.cpp

@@ -28,10 +28,14 @@ struct FfiFailure {
   explicit FfiFailure(DeRecError e) : error(e) {}
   FfiFailure(DeRecError e, std::vector<uint8_t> channelIdsJson)
       : error(e), conflictingChannelIdsJson(std::move(channelIdsJson)) {}
+  FfiFailure(DeRecError e, ProcessFailureDetails details)
+      : error(e), process(std::move(details)) {}
   DeRecError error;
   /// `restore`'s JSON array of colliding channel ids, empty for every other
   /// failure. Carried as raw bytes: parsing needs the runtime.
   std::vector<uint8_t> conflictingChannelIdsJson;
+  /// `process`'s events and failing channel, empty for every other failure.
+  ProcessFailureDetails process;
 };
 
 constexpr const char* kReentrancyMessage =
@@ -176,11 +180,13 @@ jsi::Value ProtocolHost::runAsync(
               bool unknownFailure = false;
               DeRecError capturedError{};
               std::vector<uint8_t> capturedChannelIdsJson;
+              ProcessFailureDetails capturedProcess;
               try {
                 bytes = body();
               } catch (FfiFailure& failure) {
                 capturedError = failure.error;
                 capturedChannelIdsJson = std::move(failure.conflictingChannelIdsJson);
+                capturedProcess = std::move(failure.process);
                 failed = true;
               } catch (...) {
                 // Anything other than `FfiFailure` — `std::bad_alloc` from
@@ -207,7 +213,9 @@ jsi::Value ProtocolHost::runAsync(
                                     bytes = std::move(bytes), failed,
                                     unknownFailure, capturedError,
                                     capturedChannelIdsJson =
-                                        std::move(capturedChannelIdsJson)]() mutable {
+                                        std::move(capturedChannelIdsJson),
+                                    capturedProcess =
+                                        std::move(capturedProcess)]() mutable {
                 if (state->runtimeInvalidated.load()) {
                   // Queued before the runtime was torn down, reached only
                   // afterwards. Every JSI call below — including the ones the
@@ -221,7 +229,8 @@ jsi::Value ProtocolHost::runAsync(
                     // Reuses the exact error shape every synchronous FFI
                     // wrapper throws, rather than inventing a second one for
                     // the asynchronous path.
-                    throwDeRecError(jsRt, capturedError, capturedChannelIdsJson);
+                    throwDeRecError(jsRt, capturedError, capturedChannelIdsJson,
+                                    capturedProcess);
                   }
                   if (unknownFailure) {
                     throw jsi::JSError(jsRt, "DeRec: an unexpected native error occurred");
@@ -407,12 +416,16 @@ jsi::Value ProtocolHost::get(jsi::Runtime& rt, const jsi::PropNameID& name) {
 
           auto body = [handle,
                       message = std::move(message)]() -> std::vector<uint8_t> {
-            DeRecProtocolEventsResult result =
+            DeRecProtocolProcessResult result =
                 derec_protocol_process(handle, message.data(), message.size());
+            std::vector<uint8_t> events = takeBuffer(result.events_json);
             if (result.error.code != DEREC_CODE_OK) {
-              throw FfiFailure(result.error);
+              throw FfiFailure(result.error,
+                               ProcessFailureDetails{std::move(events),
+                                                     result.has_channel_id,
+                                                     result.channel_id});
             }
-            return takeBuffer(result.events_json);
+            return events;
           };
           return runAsync(rt2, std::move(body), bytesToArrayBuffer);
         });

package/cpp/StoreCallbacks.cpp

@@ -27,7 +27,7 @@ static_assert(sizeof(ChannelStoreCallbacks) == 9 * sizeof(void*),
               "ChannelStoreCallbacks layout changed; update the bindings");
 static_assert(sizeof(SecretStoreCallbacks) == 6 * sizeof(void*),
               "SecretStoreCallbacks layout changed; update the bindings");
-static_assert(sizeof(ShareStoreCallbacks) == 8 * sizeof(void*),
+static_assert(sizeof(ShareStoreCallbacks) == 10 * sizeof(void*),
               "ShareStoreCallbacks layout changed; update the bindings");
 static_assert(sizeof(UserSecretStoreCallbacks) == 5 * sizeof(void*),
               "UserSecretStoreCallbacks layout changed; update the bindings");
@@ -320,6 +320,40 @@ CallResult toStateLoadAllResult(jsi::Runtime& rt, const jsi::Value& value) {
   return CallResult{0, std::vector<uint8_t>(text.begin(), text.end())};
 }
 
+/// `ShareStore.keepList(): Promise<number[] | null | undefined>`. Encodes the
+/// resolved value as the wire's `Option<Vec<u32>>` JSON: `null` for
+/// `null`/`undefined`, otherwise the array of versions.
+///
+/// Anything else, or an entry that is not an integer in `0..=4294967295`, is
+/// a backend failure: reading it as `null` would silently send an empty
+/// keepList, so helpers would keep every version instead of the list the
+/// application meant to send.
+CallResult toKeepListResult(jsi::Runtime& rt, const jsi::Value& value) {
+  if (value.isNull() || value.isUndefined()) {
+    return CallResult{0, {'n', 'u', 'l', 'l'}};
+  }
+  if (!value.isObject() || !value.asObject(rt).isArray(rt)) {
+    return CallResult{kBackendFailure, {}};
+  }
+  jsi::Array arr = value.asObject(rt).asArray(rt);
+  size_t n = arr.size(rt);
+  std::string text = "[";
+  for (size_t i = 0; i < n; ++i) {
+    jsi::Value entry = arr.getValueAtIndex(rt, i);
+    if (!entry.isNumber()) {
+      return CallResult{kBackendFailure, {}};
+    }
+    double version = entry.asNumber();
+    if (!(version >= 0 && version <= 4294967295.0) || version != static_cast<double>(static_cast<uint32_t>(version))) {
+      return CallResult{kBackendFailure, {}};
+    }
+    if (i != 0) text += ',';
+    text += std::to_string(static_cast<uint32_t>(version));
+  }
+  text += ']';
+  return CallResult{0, std::vector<uint8_t>(text.begin(), text.end())};
+}
+
 /// `UserSecretStore.loadLatest(): Promise<UserSecrets | null | undefined>`.
 CallResult toUserSecretsResult(jsi::Runtime& rt, const jsi::Value& value) {
   if (value.isNull() || value.isUndefined()) {
@@ -802,6 +836,53 @@ extern "C" int32_t shareStoreRemoveChannel(void* userData, uint64_t secretId, ui
   return result.code;
 }
 
+/// `ShareStore.removeVersions(secretId, channelId, versions) -> void`
+extern "C" int32_t shareStoreRemoveVersions(void* userData, uint64_t secretId, uint64_t channelId,
+                                             const uint8_t* versionsJsonPtr, size_t versionsJsonLen) {
+  auto* self = static_cast<StoreBindings*>(userData);
+  // Kept alive past this call so the lambda handed to `callSync` — which the
+  // JavaScript CallInvoker's queue may still be holding after this object's
+  // owner has released its own reference — has somewhere safe to run.
+  auto keepAlive = self->shared_from_this();
+  std::vector<uint64_t> raw = parseUnsignedJsonArray(versionsJsonPtr, versionsJsonLen);
+  std::vector<uint32_t> versions(raw.begin(), raw.end());
+  CallResult result = keepAlive->bridge().callSync(
+      [keepAlive, secretId, channelId, versions](std::function<void(CallResult)> settle) {
+        jsi::Runtime& rt = keepAlive->runtime();
+        auto store = keepAlive->shareStore();
+        auto method = store->getPropertyAsFunction(rt, "removeVersions");
+        jsi::Value promise = method.callWithThis(rt, *store, idVal(rt, secretId), idVal(rt, channelId),
+                                                  jsi::Value(rt, u32VectorToJsArray(rt, versions)));
+        keepAlive->settleFromPromise(rt, std::move(promise), std::move(settle), toVoidResult);
+      });
+  return result.code;
+}
+
+/// `ShareStore.keepList(secretId, version) -> number[] | null`
+extern "C" int32_t shareStoreKeepList(void* userData, uint64_t secretId, uint32_t version, uint8_t** outPtr,
+                                       size_t* outLen) {
+  auto* self = static_cast<StoreBindings*>(userData);
+  auto keepAlive = self->shared_from_this();
+  CallResult result =
+      keepAlive->bridge().callSync([keepAlive, secretId, version](std::function<void(CallResult)> settle) {
+        jsi::Runtime& rt = keepAlive->runtime();
+        auto store = keepAlive->shareStore();
+        auto method = store->getPropertyAsFunction(rt, "keepList");
+        jsi::Value promise =
+            method.callWithThis(rt, *store, idVal(rt, secretId), jsi::Value(static_cast<double>(version)));
+        keepAlive->settleFromPromise(rt, std::move(promise), std::move(settle), toKeepListResult);
+      });
+  if (result.code == 0) {
+    if (!writeOut(result.bytes, outPtr, outLen)) {
+      return kBackendFailure;
+    }
+  } else {
+    *outPtr = nullptr;
+    *outLen = 0;
+  }
+  return result.code;
+}
+
 /// `UserSecretStore.loadLatest(secretId) -> UserSecrets | null`
 extern "C" int32_t userSecretStoreLoadLatest(void* userData, uint64_t secretId, uint8_t** outPtr,
                                               size_t* outLen) {
@@ -1123,8 +1204,10 @@ std::shared_ptr<StoreBindings> StoreBindings::create(jsi::Runtime& rt, jsi::Obje
       shareStoreLoadAll,       // load_all
       shareStoreLatestVersion, // latest_version
       shareStoreSave,          // save
-      shareStoreRemoveChannel, // remove_channel
-      storeFreeBuffer,         // free_buffer
+      shareStoreRemoveChannel,  // remove_channel
+      shareStoreRemoveVersions, // remove_versions
+      shareStoreKeepList,       // keep_list
+      storeFreeBuffer,          // free_buffer
   };
   bindings->userSecretCallbacks_ = UserSecretStoreCallbacks{
       self,                       // user_data
@@ -1170,6 +1253,8 @@ std::shared_ptr<StoreBindings> StoreBindings::create(jsi::Runtime& rt, jsi::Obje
   requireField(rt, bindings->shareCallbacks_.latest_version, "ShareStoreCallbacks.latest_version");
   requireField(rt, bindings->shareCallbacks_.save, "ShareStoreCallbacks.save");
   requireField(rt, bindings->shareCallbacks_.remove_channel, "ShareStoreCallbacks.remove_channel");
+  requireField(rt, bindings->shareCallbacks_.remove_versions, "ShareStoreCallbacks.remove_versions");
+  requireField(rt, bindings->shareCallbacks_.keep_list, "ShareStoreCallbacks.keep_list");
   requireField(rt, bindings->shareCallbacks_.free_buffer, "ShareStoreCallbacks.free_buffer");
 
   requireField(rt, bindings->userSecretCallbacks_.user_data, "UserSecretStoreCallbacks.user_data");

package/cpp/derec_ffi.h

@@ -65,13 +65,6 @@
  */
 #define DEFAULT_THRESHOLD 3
 
-/**
- * Number of recent share versions each helper retains, absent an explicit
- * [`DeRecProtocolBuilder::with_keep_versions_count`](crate::protocol::DeRecProtocolBuilder::with_keep_versions_count) call. Sole definition
- * of the value; see [`DEFAULT_THRESHOLD`].
- */
-#define DEFAULT_KEEP_VERSIONS_COUNT 3
-
 /**
  * Maximum accepted transport URI length, in bytes.
  *
@@ -844,6 +837,11 @@ typedef struct SecretStoreCallbacks {
  * arrays (`channel_ids[]`, `versions[]`) cross the FFI as JSON
  * strings, matching the `Vec<u8>` ↔ JSON-array convention used for
  * every other wire-format buffer in this module.
+ *
+ * `keep_list` returns the JSON encoding of the application's answer:
+ * `null` for no list (the owner sends an empty `keepList` and helpers keep
+ * every version) or an array of version numbers. An empty buffer or return code `1` also
+ * means `null`.
  */
 typedef struct ShareStoreCallbacks {
   void *user_data;
@@ -878,6 +876,16 @@ typedef struct ShareStoreCallbacks {
                   const uint8_t *share_json_ptr,
                   size_t share_json_len);
   int32_t (*remove_channel)(void *user_data, uint64_t secret_id, uint64_t channel_id);
+  int32_t (*remove_versions)(void *user_data,
+                             uint64_t secret_id,
+                             uint64_t channel_id,
+                             const uint8_t *versions_json_ptr,
+                             size_t versions_json_len);
+  int32_t (*keep_list)(void *user_data,
+                       uint64_t secret_id,
+                       uint32_t version,
+                       uint8_t **out_ptr,
+                       size_t *out_len);
   void (*free_buffer)(void *user_data, uint8_t *ptr, size_t len);
 } ShareStoreCallbacks;
 
@@ -1001,6 +1009,30 @@ typedef struct DeRecProtocolEventsResult {
   struct DeRecBuffer events_json;
 } DeRecProtocolEventsResult;
 
+/**
+ * Result of [`derec_protocol_process`].
+ *
+ * A failed call still carries the events produced before the failure in
+ * `events_json`, and names the channel the failing message came from.
+ */
+typedef struct DeRecProtocolProcessResult {
+  struct DeRecError error;
+  /**
+   * UTF-8 JSON array of events, as on [`DeRecProtocolEventsResult`].
+   * Filled on success and on failure.
+   */
+  struct DeRecBuffer events_json;
+  /**
+   * Whether `channel_id` is set. False on success and when the bytes
+   * were not a decodable envelope.
+   */
+  bool has_channel_id;
+  /**
+   * The channel the failing message came from.
+   */
+  uint64_t channel_id;
+} DeRecProtocolProcessResult;
+
 /**
  * Result of [`derec_protocol_restore`].
  *
@@ -1685,7 +1717,6 @@ struct ProcessPrePairResponseMessageResult process_pre_pair_response_message(con
  *   "secret_id": "12345678901234567890",
  *   "own_transports": [{ "uri": "https://example.com/derec", "protocol": "https" }],
  *   "threshold": 3,
- *   "keep_versions_count": 3,
  *   "auto_respond_on_failure": false,
  *   "unpair_ack": 0,
  *   "auto_reply_to": false,
@@ -1730,10 +1761,8 @@ struct ProcessPrePairResponseMessageResult process_pre_pair_response_message(con
  *   two entries of the same protocol are rejected. Required: an absent or
  *   empty list is refused, since a node with no endpoint cannot be reached
  *   by any peer.
- * - `threshold` / `keep_versions_count`: omitted means
- *   [`crate::protocol::DEFAULT_THRESHOLD`] /
- *   [`crate::protocol::DEFAULT_KEEP_VERSIONS_COUNT`]. A `threshold` below
- *   `2` is rejected with `DEREC_CODE_INVALID_INPUT`.
+ * - `threshold`: omitted means [`crate::protocol::DEFAULT_THRESHOLD`]. A
+ *   `threshold` below `2` is rejected with `DEREC_CODE_INVALID_INPUT`.
  * - `unpair_ack`: `0` / `"required"` = Required, `1` / `"not_required"` =
  *   NotRequired; omitted means Required.
  *   Any other value is rejected with `DEREC_CODE_FFI_INVALID_ENUM`.
@@ -1880,7 +1909,8 @@ struct DeRecProtocolEventsResult derec_protocol_start(struct DeRecProtocolHandle
 
 /**
  * Process an inbound `DeRecMessage` envelope. See
- * [`crate::protocol::DeRecProtocol::process`].
+ * [`crate::protocol::DeRecProtocol::process`]. On failure the result still
+ * carries the events produced before it and the failing channel.
  *
  * # Safety
  *
@@ -1888,9 +1918,9 @@ struct DeRecProtocolEventsResult derec_protocol_start(struct DeRecProtocolHandle
  * [`super::derec_protocol_new`]. `message_ptr`/`message_len` must
  * describe a readable byte range.
  */
-struct DeRecProtocolEventsResult derec_protocol_process(struct DeRecProtocolHandle *handle,
-                                                        const uint8_t *message_ptr,
-                                                        size_t message_len);
+struct DeRecProtocolProcessResult derec_protocol_process(struct DeRecProtocolHandle *handle,
+                                                         const uint8_t *message_ptr,
+                                                         size_t message_len);
 
 /**
  * Advance time-driven state without an inbound message. See

package/ios/DeRecFFI.xcframework/Info.plist

@@ -10,15 +10,18 @@
 			<key>HeadersPath</key>
 			<string>Headers</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64</string>
+			<string>ios-arm64_x86_64-simulator</string>
 			<key>LibraryPath</key>
 			<string>libderec_library.a</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
+				<string>x86_64</string>
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
+			<key>SupportedPlatformVariant</key>
+			<string>simulator</string>
 		</dict>
 		<dict>
 			<key>BinaryPath</key>
@@ -26,18 +29,15 @@
 			<key>HeadersPath</key>
 			<string>Headers</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64_x86_64-simulator</string>
+			<string>ios-arm64</string>
 			<key>LibraryPath</key>
 			<string>libderec_library.a</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
-				<string>x86_64</string>
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
-			<key>SupportedPlatformVariant</key>
-			<string>simulator</string>
 		</dict>
 	</array>
 	<key>CFBundlePackageType</key>

package/ios/DeRecFFI.xcframework/ios-arm64/Headers/derec_ffi.h

@@ -65,13 +65,6 @@
  */
 #define DEFAULT_THRESHOLD 3
 
-/**
- * Number of recent share versions each helper retains, absent an explicit
- * [`DeRecProtocolBuilder::with_keep_versions_count`](crate::protocol::DeRecProtocolBuilder::with_keep_versions_count) call. Sole definition
- * of the value; see [`DEFAULT_THRESHOLD`].
- */
-#define DEFAULT_KEEP_VERSIONS_COUNT 3
-
 /**
  * Maximum accepted transport URI length, in bytes.
  *
@@ -844,6 +837,11 @@ typedef struct SecretStoreCallbacks {
  * arrays (`channel_ids[]`, `versions[]`) cross the FFI as JSON
  * strings, matching the `Vec<u8>` ↔ JSON-array convention used for
  * every other wire-format buffer in this module.
+ *
+ * `keep_list` returns the JSON encoding of the application's answer:
+ * `null` for no list (the owner sends an empty `keepList` and helpers keep
+ * every version) or an array of version numbers. An empty buffer or return code `1` also
+ * means `null`.
  */
 typedef struct ShareStoreCallbacks {
   void *user_data;
@@ -878,6 +876,16 @@ typedef struct ShareStoreCallbacks {
                   const uint8_t *share_json_ptr,
                   size_t share_json_len);
   int32_t (*remove_channel)(void *user_data, uint64_t secret_id, uint64_t channel_id);
+  int32_t (*remove_versions)(void *user_data,
+                             uint64_t secret_id,
+                             uint64_t channel_id,
+                             const uint8_t *versions_json_ptr,
+                             size_t versions_json_len);
+  int32_t (*keep_list)(void *user_data,
+                       uint64_t secret_id,
+                       uint32_t version,
+                       uint8_t **out_ptr,
+                       size_t *out_len);
   void (*free_buffer)(void *user_data, uint8_t *ptr, size_t len);
 } ShareStoreCallbacks;
 
@@ -1001,6 +1009,30 @@ typedef struct DeRecProtocolEventsResult {
   struct DeRecBuffer events_json;
 } DeRecProtocolEventsResult;
 
+/**
+ * Result of [`derec_protocol_process`].
+ *
+ * A failed call still carries the events produced before the failure in
+ * `events_json`, and names the channel the failing message came from.
+ */
+typedef struct DeRecProtocolProcessResult {
+  struct DeRecError error;
+  /**
+   * UTF-8 JSON array of events, as on [`DeRecProtocolEventsResult`].
+   * Filled on success and on failure.
+   */
+  struct DeRecBuffer events_json;
+  /**
+   * Whether `channel_id` is set. False on success and when the bytes
+   * were not a decodable envelope.
+   */
+  bool has_channel_id;
+  /**
+   * The channel the failing message came from.
+   */
+  uint64_t channel_id;
+} DeRecProtocolProcessResult;
+
 /**
  * Result of [`derec_protocol_restore`].
  *
@@ -1685,7 +1717,6 @@ struct ProcessPrePairResponseMessageResult process_pre_pair_response_message(con
  *   "secret_id": "12345678901234567890",
  *   "own_transports": [{ "uri": "https://example.com/derec", "protocol": "https" }],
  *   "threshold": 3,
- *   "keep_versions_count": 3,
  *   "auto_respond_on_failure": false,
  *   "unpair_ack": 0,
  *   "auto_reply_to": false,
@@ -1730,10 +1761,8 @@ struct ProcessPrePairResponseMessageResult process_pre_pair_response_message(con
  *   two entries of the same protocol are rejected. Required: an absent or
  *   empty list is refused, since a node with no endpoint cannot be reached
  *   by any peer.
- * - `threshold` / `keep_versions_count`: omitted means
- *   [`crate::protocol::DEFAULT_THRESHOLD`] /
- *   [`crate::protocol::DEFAULT_KEEP_VERSIONS_COUNT`]. A `threshold` below
- *   `2` is rejected with `DEREC_CODE_INVALID_INPUT`.
+ * - `threshold`: omitted means [`crate::protocol::DEFAULT_THRESHOLD`]. A
+ *   `threshold` below `2` is rejected with `DEREC_CODE_INVALID_INPUT`.
  * - `unpair_ack`: `0` / `"required"` = Required, `1` / `"not_required"` =
  *   NotRequired; omitted means Required.
  *   Any other value is rejected with `DEREC_CODE_FFI_INVALID_ENUM`.
@@ -1880,7 +1909,8 @@ struct DeRecProtocolEventsResult derec_protocol_start(struct DeRecProtocolHandle
 
 /**
  * Process an inbound `DeRecMessage` envelope. See
- * [`crate::protocol::DeRecProtocol::process`].
+ * [`crate::protocol::DeRecProtocol::process`]. On failure the result still
+ * carries the events produced before it and the failing channel.
  *
  * # Safety
  *
@@ -1888,9 +1918,9 @@ struct DeRecProtocolEventsResult derec_protocol_start(struct DeRecProtocolHandle
  * [`super::derec_protocol_new`]. `message_ptr`/`message_len` must
  * describe a readable byte range.
  */
-struct DeRecProtocolEventsResult derec_protocol_process(struct DeRecProtocolHandle *handle,
-                                                        const uint8_t *message_ptr,
-                                                        size_t message_len);
+struct DeRecProtocolProcessResult derec_protocol_process(struct DeRecProtocolHandle *handle,
+                                                         const uint8_t *message_ptr,
+                                                         size_t message_len);
 
 /**
  * Advance time-driven state without an inbound message. See

package/ios/DeRecFFI.xcframework/ios-arm64_x86_64-simulator/Headers/derec_ffi.h

@@ -65,13 +65,6 @@
  */
 #define DEFAULT_THRESHOLD 3
 
-/**
- * Number of recent share versions each helper retains, absent an explicit
- * [`DeRecProtocolBuilder::with_keep_versions_count`](crate::protocol::DeRecProtocolBuilder::with_keep_versions_count) call. Sole definition
- * of the value; see [`DEFAULT_THRESHOLD`].
- */
-#define DEFAULT_KEEP_VERSIONS_COUNT 3
-
 /**
  * Maximum accepted transport URI length, in bytes.
  *
@@ -844,6 +837,11 @@ typedef struct SecretStoreCallbacks {
  * arrays (`channel_ids[]`, `versions[]`) cross the FFI as JSON
  * strings, matching the `Vec<u8>` ↔ JSON-array convention used for
  * every other wire-format buffer in this module.
+ *
+ * `keep_list` returns the JSON encoding of the application's answer:
+ * `null` for no list (the owner sends an empty `keepList` and helpers keep
+ * every version) or an array of version numbers. An empty buffer or return code `1` also
+ * means `null`.
  */
 typedef struct ShareStoreCallbacks {
   void *user_data;
@@ -878,6 +876,16 @@ typedef struct ShareStoreCallbacks {
                   const uint8_t *share_json_ptr,
                   size_t share_json_len);
   int32_t (*remove_channel)(void *user_data, uint64_t secret_id, uint64_t channel_id);
+  int32_t (*remove_versions)(void *user_data,
+                             uint64_t secret_id,
+                             uint64_t channel_id,
+                             const uint8_t *versions_json_ptr,
+                             size_t versions_json_len);
+  int32_t (*keep_list)(void *user_data,
+                       uint64_t secret_id,
+                       uint32_t version,
+                       uint8_t **out_ptr,
+                       size_t *out_len);
   void (*free_buffer)(void *user_data, uint8_t *ptr, size_t len);
 } ShareStoreCallbacks;
 
@@ -1001,6 +1009,30 @@ typedef struct DeRecProtocolEventsResult {
   struct DeRecBuffer events_json;
 } DeRecProtocolEventsResult;
 
+/**
+ * Result of [`derec_protocol_process`].
+ *
+ * A failed call still carries the events produced before the failure in
+ * `events_json`, and names the channel the failing message came from.
+ */
+typedef struct DeRecProtocolProcessResult {
+  struct DeRecError error;
+  /**
+   * UTF-8 JSON array of events, as on [`DeRecProtocolEventsResult`].
+   * Filled on success and on failure.
+   */
+  struct DeRecBuffer events_json;
+  /**
+   * Whether `channel_id` is set. False on success and when the bytes
+   * were not a decodable envelope.
+   */
+  bool has_channel_id;
+  /**
+   * The channel the failing message came from.
+   */
+  uint64_t channel_id;
+} DeRecProtocolProcessResult;
+
 /**
  * Result of [`derec_protocol_restore`].
  *
@@ -1685,7 +1717,6 @@ struct ProcessPrePairResponseMessageResult process_pre_pair_response_message(con
  *   "secret_id": "12345678901234567890",
  *   "own_transports": [{ "uri": "https://example.com/derec", "protocol": "https" }],
  *   "threshold": 3,
- *   "keep_versions_count": 3,
  *   "auto_respond_on_failure": false,
  *   "unpair_ack": 0,
  *   "auto_reply_to": false,
@@ -1730,10 +1761,8 @@ struct ProcessPrePairResponseMessageResult process_pre_pair_response_message(con
  *   two entries of the same protocol are rejected. Required: an absent or
  *   empty list is refused, since a node with no endpoint cannot be reached
  *   by any peer.
- * - `threshold` / `keep_versions_count`: omitted means
- *   [`crate::protocol::DEFAULT_THRESHOLD`] /
- *   [`crate::protocol::DEFAULT_KEEP_VERSIONS_COUNT`]. A `threshold` below
- *   `2` is rejected with `DEREC_CODE_INVALID_INPUT`.
+ * - `threshold`: omitted means [`crate::protocol::DEFAULT_THRESHOLD`]. A
+ *   `threshold` below `2` is rejected with `DEREC_CODE_INVALID_INPUT`.
  * - `unpair_ack`: `0` / `"required"` = Required, `1` / `"not_required"` =
  *   NotRequired; omitted means Required.
  *   Any other value is rejected with `DEREC_CODE_FFI_INVALID_ENUM`.
@@ -1880,7 +1909,8 @@ struct DeRecProtocolEventsResult derec_protocol_start(struct DeRecProtocolHandle
 
 /**
  * Process an inbound `DeRecMessage` envelope. See
- * [`crate::protocol::DeRecProtocol::process`].
+ * [`crate::protocol::DeRecProtocol::process`]. On failure the result still
+ * carries the events produced before it and the failing channel.
  *
  * # Safety
  *
@@ -1888,9 +1918,9 @@ struct DeRecProtocolEventsResult derec_protocol_start(struct DeRecProtocolHandle
  * [`super::derec_protocol_new`]. `message_ptr`/`message_len` must
  * describe a readable byte range.
  */
-struct DeRecProtocolEventsResult derec_protocol_process(struct DeRecProtocolHandle *handle,
-                                                        const uint8_t *message_ptr,
-                                                        size_t message_len);
+struct DeRecProtocolProcessResult derec_protocol_process(struct DeRecProtocolHandle *handle,
+                                                         const uint8_t *message_ptr,
+                                                         size_t message_len);
 
 /**
  * Advance time-driven state without an inbound message. See

package/ios/DeRecFFI.xcframework/ios-arm64_x86_64-simulator/libderec_library.a

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/ios/DeRecFFI.xcframework/ios-arm64_x86_64-simulator/libderec_library.a
-size: 38440744 bytes
-sha256: d9c6ce3666c5b27a2fad3b79a4e82af22204b72fb203ddb08bc5a6d6cc498bab
+size: 38454248 bytes
+sha256: 8e4fa480cdb006907de3fbd3c13011ee89816dc78b4c1c22b6a730297f29521a

package/lib/errors.d.ts

@@ -1,3 +1,4 @@
+import type { DeRecEvent } from './types';
 /**
  * Every category name `derec_error_category_name` can return, and no others.
  *
@@ -27,4 +28,12 @@ export interface DeRecError {
      * Clear exactly these and retry `restore`.
      */
     channel_ids?: string[];
+    /** The channel the failing inbound message arrived on, when `process()` could tell. */
+    channel_id?: string;
+    /**
+     * On a failed `process()`: the events it produced before failing, such as
+     * sharing-round and unpair timeouts. They are not reported again, so
+     * handle them as you would a successful call's events.
+     */
+    events?: DeRecEvent[];
 }

package/lib/protocol.d.ts

@@ -38,9 +38,9 @@ export declare function buildRestoreParams(recoveredSecret: Extract<DeRecEvent,
  *
  * Every value the caller supplies is forwarded verbatim — defaults, clamping
  * and the meaning of a disabled cleanup policy are library decisions.
- * `threshold`, `keep_versions_count`, `auto_respond_on_failure`,
- * `unpair_ack`, `auto_reply_to` and `auto_accept` are omitted entirely from
- * the emitted config unless their setter was called: `ProtocolConfig` has a
+ * `threshold`, `auto_respond_on_failure`, `unpair_ack`, `auto_reply_to`
+ * and `auto_accept` are omitted entirely from the emitted config unless
+ * their setter was called: `ProtocolConfig` has a
  * `#[serde(default = "...")]` on each of them, reading the same constants
  * `DeRecProtocolBuilder::new` uses, so an absent key resolves to the
  * library's own default rather than one frozen into this shim.
@@ -74,8 +74,6 @@ export declare class DeRecProtocolBuilder {
     withOwnTransports(transports: Endpoint[]): this;
     /** Default: 3. */
     withThreshold(threshold: number): this;
-    /** Default: 3. */
-    withKeepVersionsCount(count: number): this;
     /**
      * Every field is optional; not calling this at all leaves all four at the
      * library's defaults — `timeouts` is genuinely absent from the JSON in
@@ -191,11 +189,24 @@ export declare class DeRecProtocol {
     accept(actionBytes: Uint8Array): Promise<DeRecEvent[]>;
     reject(actionBytes: Uint8Array, status: StatusEnum, memo: string): Promise<void>;
     getFingerprint(channelId: bigint | number): Promise<string>;
+    /**
+     * Verify `fingerprint` against the channel's locally-derived one. On
+     * match, the channel transitions from `Pending` to `Paired`. Returns
+     * `true` on confirmation, `false` on mismatch.
+     *
+     * On a replica destination, confirming is also the decision to adopt the
+     * group's vault: the source's publish is then installed as it arrives,
+     * with no further prompt. Ask the user before calling this; to decline,
+     * never confirm.
+     */
     verifyFingerprint(channelId: bigint | number, fingerprint: string): Promise<boolean>;
     removeExpiredChannels(olderThanSecs: number): Promise<string[]>;
     /**
      * Rebuild this protocol's `secret_id` namespace from a recovered `Secret`.
      * Pass the `secret` carried by the `SecretRecovered` event verbatim.
+     * Recovery and restore are separate steps on purpose: `SecretRecovered`
+     * writes nothing. Show the user what was recovered, or ask them, before
+     * calling `restore`, which commits it to this device.
      * A helper or member whose `transports` is empty gets no channel: it is
      * reported as a `PeerNotRestored` event in the returned array and the rest
      * of the roster is restored.

package/lib/protocol.js

@@ -234,9 +234,9 @@ function toBigInt(id) {
  *
  * Every value the caller supplies is forwarded verbatim — defaults, clamping
  * and the meaning of a disabled cleanup policy are library decisions.
- * `threshold`, `keep_versions_count`, `auto_respond_on_failure`,
- * `unpair_ack`, `auto_reply_to` and `auto_accept` are omitted entirely from
- * the emitted config unless their setter was called: `ProtocolConfig` has a
+ * `threshold`, `auto_respond_on_failure`, `unpair_ack`, `auto_reply_to`
+ * and `auto_accept` are omitted entirely from the emitted config unless
+ * their setter was called: `ProtocolConfig` has a
  * `#[serde(default = "...")]` on each of them, reading the same constants
  * `DeRecProtocolBuilder::new` uses, so an absent key resolves to the
  * library's own default rather than one frozen into this shim.
@@ -295,11 +295,6 @@ class DeRecProtocolBuilder {
         this.config.threshold = threshold;
         return this;
     }
-    /** Default: 3. */
-    withKeepVersionsCount(count) {
-        this.config.keep_versions_count = count;
-        return this;
-    }
     /**
      * Every field is optional; not calling this at all leaves all four at the
      * library's defaults — `timeouts` is genuinely absent from the JSON in
@@ -478,7 +473,17 @@ class DeRecProtocol {
         return decodeEvents(buffer);
     }
     async process(message) {
-        const buffer = (await this.host.process(message));
+        let buffer;
+        try {
+            buffer = (await this.host.process(message));
+        }
+        catch (error) {
+            const failure = error;
+            if (Array.isArray(failure.events)) {
+                failure.events = reviveEventBytes(failure.events);
+            }
+            throw error;
+        }
         return decodeEvents(buffer);
     }
     async tick() {
@@ -495,6 +500,16 @@ class DeRecProtocol {
     async getFingerprint(channelId) {
         return (await this.host.getFingerprint(toBigInt(channelId)));
     }
+    /**
+     * Verify `fingerprint` against the channel's locally-derived one. On
+     * match, the channel transitions from `Pending` to `Paired`. Returns
+     * `true` on confirmation, `false` on mismatch.
+     *
+     * On a replica destination, confirming is also the decision to adopt the
+     * group's vault: the source's publish is then installed as it arrives,
+     * with no further prompt. Ask the user before calling this; to decline,
+     * never confirm.
+     */
     async verifyFingerprint(channelId, fingerprint) {
         return (await this.host.verifyFingerprint(toBigInt(channelId), fingerprint));
     }
@@ -505,6 +520,9 @@ class DeRecProtocol {
     /**
      * Rebuild this protocol's `secret_id` namespace from a recovered `Secret`.
      * Pass the `secret` carried by the `SecretRecovered` event verbatim.
+     * Recovery and restore are separate steps on purpose: `SecretRecovered`
+     * writes nothing. Show the user what was recovered, or ask them, before
+     * calling `restore`, which commits it to this device.
      * A helper or member whose `transports` is empty gets no channel: it is
      * reported as a `PeerNotRestored` event in the returned array and the rest
      * of the roster is restored.

package/lib/types.d.ts

@@ -191,6 +191,35 @@ export interface ShareStore {
     save(secretId: string, channelId: string, share: Share): Promise<void>;
     latestVersion(secretId: string): Promise<number | null>;
     removeChannel(secretId: string, channelId: string): Promise<void>;
+    /**
+     * Drop the shares stored under `(secretId, channelId)` at each of
+     * `versions`. Idempotent: a version that is not stored is skipped, and
+     * an empty array is a no-op.
+     *
+     * A helper calls this to apply `StoreShareRequestMessage.keepList`, the
+     * complete set of versions the owner wants retained: every stored
+     * version outside it is removed once the incoming share is persisted.
+     * Shares under other channels or partitions must be left untouched.
+     */
+    removeVersions(secretId: string, channelId: string, versions: number[]): Promise<void>;
+    /**
+     * Owner only: the versions every helper keeps after the owner distributes
+     * `version`. Asked once per sharing round, before anything is sent,
+     * including the rounds the library starts itself; the answer becomes
+     * `keepList` for every helper.
+     *
+     * Return `null` or `undefined` to send no `keepList` (it goes out empty):
+     * helpers then keep every version they hold. An app that wants to cap how
+     * many versions helpers retain returns that cap here. A returned list is
+     * used as is, plus `version`, which the library always adds. Helpers
+     * delete every version that is not listed, so list every version that
+     * could still become the latest: those that committed (for example, whose
+     * `SharingComplete` reported `threshold_met`) and those whose round is
+     * still open. Leave out only versions whose round failed or that the user
+     * rolled back; a list that leaves out too much can make the secret
+     * unrecoverable.
+     */
+    keepList(secretId: string, version: number): Promise<number[] | null | undefined>;
 }
 export interface UserSecretEntry {
     id: Uint8Array;
@@ -519,6 +548,15 @@ export interface Timeouts {
 /** `ReplicaDiscovery` takes no parameters: the group and this device's own version
  *  are both read from the stores. The argument may be omitted entirely. */
 export type ReplicaDiscoveryParams = Record<string, never>;
+/** Any member may remove any member, the source included: a lost or stolen
+ *  source must be removable by the devices that remain, and the library
+ *  checks no role. Ask the user before starting this flow, above all when it
+ *  names the source. Removing the source promotes the first remaining member
+ *  in the order the channel store's `listReplicas` returns. The removed
+ *  member is not asked and gets no event when told to leave: when a roster
+ *  excluding it arrives it drops its whole `secret_id` partition and emits
+ *  `SelfRemovedFromGroup`. The secret survives on the remaining members and
+ *  the helpers. */
 export interface UnpairReplicaParams {
     /** The member to remove, as a **decimal** `u64` string — the same form
      *  `ReplicaPaired.peer_replica_id` hands back. A value naming no current
@@ -601,8 +639,11 @@ export type DeRecEvent = {
 }
 /** A group member refused a secret sync. Keyed by `replica_id`, not
  *  `channel_id`: every member answers on the one group channel. A
- *  `VERSION_CONFLICT` status means the round must be resolved and
- *  republished at a new version. */
+ *  `VERSION_CONFLICT` status means another member holds a different copy
+ *  of this version: do not publish from this device again until the
+ *  conflict is resolved. Run `start(FlowKind.ReplicaDiscovery)` to receive
+ *  the group's copy as `ReplicaVersionConflict`, merge, and publish the
+ *  result once with `start(FlowKind.ProtectSecret)`. */
  | {
     type: "ReplicaSyncRejected";
     replica_id: string;
@@ -636,7 +677,8 @@ export type DeRecEvent = {
 /** This device left the group and dropped its whole `secret_id` partition —
  *  group channel, helper channels, shares, secrets and the snapshot. Fires
  *  only once it was told to leave *and* has since seen a roster excluding
- *  it; absence alone never destroys a copy of the secret. */
+ *  it; absence alone never destroys a copy of the secret. The teardown is
+ *  automatic: this device is not asked first and gets no earlier event. */
  | {
     type: "SelfRemovedFromGroup";
     version: number;
@@ -662,6 +704,16 @@ export type DeRecEvent = {
     type: "ShareVerified";
     channel_id: string;
     version: number;
+}
+/** A helper refused a verification challenge: its response carried a
+ *  non-OK `status` instead of a proof. The challenge is spent; a new
+ *  `VerifyShares` round challenges the helper again. */
+ | {
+    type: "ShareVerifyRejected";
+    channel_id: string;
+    version: number;
+    status: StatusEnum;
+    memo: string;
 } | {
     type: "SecretsDiscovered";
     channel_id: string;
@@ -682,6 +734,33 @@ export type DeRecEvent = {
     shares_received: number;
     error: string;
 }
+/** A helper refused a recovery share request: its response carried a
+ *  non-OK `status` (e.g. `UNKNOWN_SHARE_VERSION`) instead of a share. The
+ *  refusal is not collected — it does not count towards `shares_received`
+ *  and the recovery stays open for the other helpers' shares — but it does
+ *  answer that helper's `RecoverSecretStarted`. */
+ | {
+    type: "RecoveryShareRefused";
+    channel_id: string;
+    version: number;
+    status: StatusEnum;
+    memo: string;
+}
+/** A helper answered with a share that cannot be part of the secret;
+ *  `reason` says how it failed. `Malformed` and `InvalidProof` are judged
+ *  on arrival; `Inconsistent` (valid on its own but disagreeing with the
+ *  shares the secret was rebuilt from) is reported alongside
+ *  `SecretRecovered`, once per helper. The share is set aside — it does
+ *  not count towards `shares_received` and never blocks the recovery. An
+ *  honest helper never sends one, so the app may treat it as a sign of a
+ *  damaged or compromised helper, e.g. offer to unpair it. It also
+ *  answers that helper's `RecoverSecretStarted`. */
+ | {
+    type: "RecoveryShareCorrupted";
+    channel_id: string;
+    version: number;
+    reason: CorruptionReason;
+}
 /** Recovery completed — the typed `Secret` snapshot the owner
  *  originally protected. Mirrors `ReplicaSecretReceived.secret`:
  *  `secrets` is the user-facing `Vec<UserSecret>` the application
@@ -866,7 +945,10 @@ export type DeRecEvent = {
  *  `ReplicaSyncRejected`. Both copies are complete states — the held one
  *  is in the local stores, the incoming one is `secret`. Resolve by
  *  publishing the chosen state with `start(FlowKind.ProtectSecret)`; the
- *  next version supersedes both on every member and helper.
+ *  next version supersedes both on every member and helper. Until then,
+ *  do not publish from this device: any further `ProtectSecret` is a
+ *  higher version that every other member applies over its own copy,
+ *  losing the change it never merged.
  *
  *  `held_author_replica_id` / `incoming_author_replica_id` are the
  *  decimal `replica_id` of each copy's publisher, or `null` when that
@@ -1177,6 +1259,13 @@ export type IgnoreReason = "PendingVerification" | "Expired";
 /** Why a `PeerNotRestored` event left a roster entry without a channel.
  *  Matches the Rust `NotRestoredReason` discriminants one-for-one. */
 export type NotRestoredReason = "NoTransports";
+/** Why a `RecoveryShareCorrupted` event set a helper's share aside.
+ *  Matches the Rust `CorruptionReason` discriminants one-for-one:
+ *  `Malformed` — no decodable share for the requested secret and version;
+ *  `InvalidProof` — the share fails its own Merkle proof;
+ *  `Inconsistent` — valid on its own, but its commitment root or ciphertext
+ *  disagrees with the shares the secret was rebuilt from. */
+export type CorruptionReason = "Malformed" | "InvalidProof" | "Inconsistent";
 /**
  * The label vocabulary for `ActionRequired.action_kind` and
  * `AutoAccepted.action_kind` — one value per pending-action kind the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@derec-alliance/react-native",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "React Native bindings for derec-library, the Rust SDK for the DeRec protocol.",
   "license": "Apache-2.0",
   "repository": {

package/src/errors.ts

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) 2026 DeRec Alliance. All rights reserved.
 
+import type { DeRecEvent } from './types';
+
 /**
  * Every category name `derec_error_category_name` can return, and no others.
  *
@@ -49,4 +51,12 @@ export interface DeRecError {
    * Clear exactly these and retry `restore`.
    */
   channel_ids?: string[];
+  /** The channel the failing inbound message arrived on, when `process()` could tell. */
+  channel_id?: string;
+  /**
+   * On a failed `process()`: the events it produced before failing, such as
+   * sharing-round and unpair timeouts. They are not reported again, so
+   * handle them as you would a successful call's events.
+   */
+  events?: DeRecEvent[];
 }

package/src/protocol.ts

@@ -280,9 +280,9 @@ function toBigInt(id: bigint | number): bigint {
  *
  * Every value the caller supplies is forwarded verbatim — defaults, clamping
  * and the meaning of a disabled cleanup policy are library decisions.
- * `threshold`, `keep_versions_count`, `auto_respond_on_failure`,
- * `unpair_ack`, `auto_reply_to` and `auto_accept` are omitted entirely from
- * the emitted config unless their setter was called: `ProtocolConfig` has a
+ * `threshold`, `auto_respond_on_failure`, `unpair_ack`, `auto_reply_to`
+ * and `auto_accept` are omitted entirely from the emitted config unless
+ * their setter was called: `ProtocolConfig` has a
  * `#[serde(default = "...")]` on each of them, reading the same constants
  * `DeRecProtocolBuilder::new` uses, so an absent key resolves to the
  * library's own default rather than one frozen into this shim.
@@ -352,12 +352,6 @@ export class DeRecProtocolBuilder {
     return this;
   }
 
-  /** Default: 3. */
-  withKeepVersionsCount(count: number): this {
-    this.config.keep_versions_count = count;
-    return this;
-  }
-
   /**
    * Every field is optional; not calling this at all leaves all four at the
    * library's defaults — `timeouts` is genuinely absent from the JSON in
@@ -579,7 +573,16 @@ export class DeRecProtocol {
   }
 
   async process(message: Uint8Array): Promise<DeRecEvent[]> {
-    const buffer = (await this.host.process(message)) as ArrayBuffer;
+    let buffer: ArrayBuffer;
+    try {
+      buffer = (await this.host.process(message)) as ArrayBuffer;
+    } catch (error) {
+      const failure = error as { events?: unknown };
+      if (Array.isArray(failure.events)) {
+        failure.events = reviveEventBytes(failure.events);
+      }
+      throw error;
+    }
     return decodeEvents(buffer);
   }
 
@@ -601,6 +604,16 @@ export class DeRecProtocol {
     return (await this.host.getFingerprint(toBigInt(channelId))) as string;
   }
 
+  /**
+   * Verify `fingerprint` against the channel's locally-derived one. On
+   * match, the channel transitions from `Pending` to `Paired`. Returns
+   * `true` on confirmation, `false` on mismatch.
+   *
+   * On a replica destination, confirming is also the decision to adopt the
+   * group's vault: the source's publish is then installed as it arrives,
+   * with no further prompt. Ask the user before calling this; to decline,
+   * never confirm.
+   */
   async verifyFingerprint(channelId: bigint | number, fingerprint: string): Promise<boolean> {
     return (await this.host.verifyFingerprint(toBigInt(channelId), fingerprint)) as boolean;
   }
@@ -613,6 +626,9 @@ export class DeRecProtocol {
   /**
    * Rebuild this protocol's `secret_id` namespace from a recovered `Secret`.
    * Pass the `secret` carried by the `SecretRecovered` event verbatim.
+   * Recovery and restore are separate steps on purpose: `SecretRecovered`
+   * writes nothing. Show the user what was recovered, or ask them, before
+   * calling `restore`, which commits it to this device.
    * A helper or member whose `transports` is empty gets no channel: it is
    * reported as a `PeerNotRestored` event in the returned array and the rest
    * of the roster is restored.

package/src/types.ts

@@ -261,6 +261,42 @@ export interface ShareStore {
   save(secretId: string, channelId: string, share: Share): Promise<void>;
   latestVersion(secretId: string): Promise<number | null>;
   removeChannel(secretId: string, channelId: string): Promise<void>;
+  /**
+   * Drop the shares stored under `(secretId, channelId)` at each of
+   * `versions`. Idempotent: a version that is not stored is skipped, and
+   * an empty array is a no-op.
+   *
+   * A helper calls this to apply `StoreShareRequestMessage.keepList`, the
+   * complete set of versions the owner wants retained: every stored
+   * version outside it is removed once the incoming share is persisted.
+   * Shares under other channels or partitions must be left untouched.
+   */
+  removeVersions(
+    secretId: string,
+    channelId: string,
+    versions: number[],
+  ): Promise<void>;
+  /**
+   * Owner only: the versions every helper keeps after the owner distributes
+   * `version`. Asked once per sharing round, before anything is sent,
+   * including the rounds the library starts itself; the answer becomes
+   * `keepList` for every helper.
+   *
+   * Return `null` or `undefined` to send no `keepList` (it goes out empty):
+   * helpers then keep every version they hold. An app that wants to cap how
+   * many versions helpers retain returns that cap here. A returned list is
+   * used as is, plus `version`, which the library always adds. Helpers
+   * delete every version that is not listed, so list every version that
+   * could still become the latest: those that committed (for example, whose
+   * `SharingComplete` reported `threshold_met`) and those whose round is
+   * still open. Leave out only versions whose round failed or that the user
+   * rolled back; a list that leaves out too much can make the secret
+   * unrecoverable.
+   */
+  keepList(
+    secretId: string,
+    version: number,
+  ): Promise<number[] | null | undefined>;
 }
 
 export interface UserSecretEntry {
@@ -653,6 +689,15 @@ export interface Timeouts {
  *  are both read from the stores. The argument may be omitted entirely. */
 export type ReplicaDiscoveryParams = Record<string, never>;
 
+/** Any member may remove any member, the source included: a lost or stolen
+ *  source must be removable by the devices that remain, and the library
+ *  checks no role. Ask the user before starting this flow, above all when it
+ *  names the source. Removing the source promotes the first remaining member
+ *  in the order the channel store's `listReplicas` returns. The removed
+ *  member is not asked and gets no event when told to leave: when a roster
+ *  excluding it arrives it drops its whole `secret_id` partition and emits
+ *  `SelfRemovedFromGroup`. The secret survives on the remaining members and
+ *  the helpers. */
 export interface UnpairReplicaParams {
   /** The member to remove, as a **decimal** `u64` string — the same form
    *  `ReplicaPaired.peer_replica_id` hands back. A value naming no current
@@ -724,8 +769,11 @@ export type DeRecEvent =
   | { type: "SharingComplete"; version: number; confirmed_count: number; failed_count: number; threshold_met: boolean }
   /** A group member refused a secret sync. Keyed by `replica_id`, not
    *  `channel_id`: every member answers on the one group channel. A
-   *  `VERSION_CONFLICT` status means the round must be resolved and
-   *  republished at a new version. */
+   *  `VERSION_CONFLICT` status means another member holds a different copy
+   *  of this version: do not publish from this device again until the
+   *  conflict is resolved. Run `start(FlowKind.ReplicaDiscovery)` to receive
+   *  the group's copy as `ReplicaVersionConflict`, merge, and publish the
+   *  result once with `start(FlowKind.ProtectSecret)`. */
   | {
       type: "ReplicaSyncRejected";
       replica_id: string;
@@ -748,7 +796,8 @@ export type DeRecEvent =
   /** This device left the group and dropped its whole `secret_id` partition —
    *  group channel, helper channels, shares, secrets and the snapshot. Fires
    *  only once it was told to leave *and* has since seen a roster excluding
-   *  it; absence alone never destroys a copy of the secret. */
+   *  it; absence alone never destroys a copy of the secret. The teardown is
+   *  automatic: this device is not asked first and gets no earlier event. */
   | { type: "SelfRemovedFromGroup"; version: number }
   /** A replica catch-up finished. `fetched_from` is absent when this device
    *  was already current, in which case no hydration event follows. */
@@ -764,6 +813,10 @@ export type DeRecEvent =
    *  library keeps no durable per-member sync state. */
   | { type: "ReplicaSyncComplete"; version: number; synced: string[]; behind: string[] }
   | { type: "ShareVerified"; channel_id: string; version: number }
+  /** A helper refused a verification challenge: its response carried a
+   *  non-OK `status` instead of a proof. The challenge is spent; a new
+   *  `VerifyShares` round challenges the helper again. */
+  | { type: "ShareVerifyRejected"; channel_id: string; version: number; status: StatusEnum; memo: string }
   | {
       type: "SecretsDiscovered";
       channel_id: string;
@@ -772,6 +825,22 @@ export type DeRecEvent =
     }
   | { type: "RecoveryShareReceived"; channel_id: string; shares_received: number }
   | { type: "RecoveryShareError"; channel_id: string; shares_received: number; error: string }
+  /** A helper refused a recovery share request: its response carried a
+   *  non-OK `status` (e.g. `UNKNOWN_SHARE_VERSION`) instead of a share. The
+   *  refusal is not collected — it does not count towards `shares_received`
+   *  and the recovery stays open for the other helpers' shares — but it does
+   *  answer that helper's `RecoverSecretStarted`. */
+  | { type: "RecoveryShareRefused"; channel_id: string; version: number; status: StatusEnum; memo: string }
+  /** A helper answered with a share that cannot be part of the secret;
+   *  `reason` says how it failed. `Malformed` and `InvalidProof` are judged
+   *  on arrival; `Inconsistent` (valid on its own but disagreeing with the
+   *  shares the secret was rebuilt from) is reported alongside
+   *  `SecretRecovered`, once per helper. The share is set aside — it does
+   *  not count towards `shares_received` and never blocks the recovery. An
+   *  honest helper never sends one, so the app may treat it as a sign of a
+   *  damaged or compromised helper, e.g. offer to unpair it. It also
+   *  answers that helper's `RecoverSecretStarted`. */
+  | { type: "RecoveryShareCorrupted"; channel_id: string; version: number; reason: CorruptionReason }
   /** Recovery completed — the typed `Secret` snapshot the owner
    *  originally protected. Mirrors `ReplicaSecretReceived.secret`:
    *  `secrets` is the user-facing `Vec<UserSecret>` the application
@@ -949,7 +1018,10 @@ export type DeRecEvent =
    *  `ReplicaSyncRejected`. Both copies are complete states — the held one
    *  is in the local stores, the incoming one is `secret`. Resolve by
    *  publishing the chosen state with `start(FlowKind.ProtectSecret)`; the
-   *  next version supersedes both on every member and helper.
+   *  next version supersedes both on every member and helper. Until then,
+   *  do not publish from this device: any further `ProtectSecret` is a
+   *  higher version that every other member applies over its own copy,
+   *  losing the change it never merged.
    *
    *  `held_author_replica_id` / `incoming_author_replica_id` are the
    *  decimal `replica_id` of each copy's publisher, or `null` when that
@@ -1232,6 +1304,14 @@ export type IgnoreReason = "PendingVerification" | "Expired";
  *  Matches the Rust `NotRestoredReason` discriminants one-for-one. */
 export type NotRestoredReason = "NoTransports";
 
+/** Why a `RecoveryShareCorrupted` event set a helper's share aside.
+ *  Matches the Rust `CorruptionReason` discriminants one-for-one:
+ *  `Malformed` — no decodable share for the requested secret and version;
+ *  `InvalidProof` — the share fails its own Merkle proof;
+ *  `Inconsistent` — valid on its own, but its commitment root or ciphertext
+ *  disagrees with the shares the secret was rebuilt from. */
+export type CorruptionReason = "Malformed" | "InvalidProof" | "Inconsistent";
+
 /**
  * The label vocabulary for `ActionRequired.action_kind` and
  * `AutoAccepted.action_kind` — one value per pending-action kind the