rn-update 1.0.0

package/cpp/update_flow_core/flow_json.h

@@ -0,0 +1,121 @@
+/**
+ * [INPUT]: 依赖标准字符串/容器与 TypeScript 决策层所需的 JavaScript 值语义
+ * [OUTPUT]: 对外提供 Value、Parse、Stringify、truthiness 与 primitive strict-equality 模型
+ * [POS]: update_flow_core 的 JSON 防腐层，以最小实现复刻向量所依赖的 JS 对象和 undefined 行为
+ */
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <utility>
+#include <vector>
+
+// Minimal JSON document model for the update-flow decision layer.
+//
+// Deliberately mirrors JavaScript object semantics where the ported decision
+// logic depends on them, because the golden vectors are generated by the TS
+// reference implementation and compared as serialized strings:
+//  - object members keep insertion order, and overwriting an existing key
+//    keeps its original position (JS spread/assignment semantics);
+//  - Kind::Undefined is distinct from Kind::Null: undefined-valued members
+//    are skipped by Stringify (like JSON.stringify), null is emitted;
+//  - Truthy() implements JS truthiness (undefined/null/false/0/NaN/'' are
+//    falsy; empty arrays and objects are truthy);
+//  - StrictEquals() implements === for primitives only (never for
+//    arrays/objects — reference equality cannot hold across a parse).
+namespace flowjson {
+
+class Value;
+using Members = std::vector<std::pair<std::string, Value>>;
+using Elements = std::vector<Value>;
+
+class Value {
+ public:
+  enum class Kind { Undefined, Null, Bool, Number, String, Array, Object };
+
+  Value() = default;
+  static Value Undefined() { return Value(); }
+  static Value Null() { return Value(Kind::Null); }
+  static Value Bool(bool b) {
+    Value v(Kind::Bool);
+    v.bool_ = b;
+    return v;
+  }
+  static Value Number(double n) {
+    Value v(Kind::Number);
+    v.number_ = n;
+    return v;
+  }
+  static Value String(std::string s) {
+    Value v(Kind::String);
+    v.string_ = std::move(s);
+    return v;
+  }
+  static Value Array() { return Value(Kind::Array); }
+  static Value Object() { return Value(Kind::Object); }
+
+  Kind kind() const { return kind_; }
+  bool IsUndefined() const { return kind_ == Kind::Undefined; }
+  bool IsArray() const { return kind_ == Kind::Array; }
+  bool IsObject() const { return kind_ == Kind::Object; }
+  bool IsBool() const { return kind_ == Kind::Bool; }
+  bool IsNumber() const { return kind_ == Kind::Number; }
+  bool IsString() const { return kind_ == Kind::String; }
+
+  bool AsBool() const { return bool_; }
+  double AsNumber() const { return number_; }
+  const std::string& AsString() const { return string_; }
+
+  bool Truthy() const;
+
+  // Array access.
+  const Elements& elements() const { return elements_; }
+  void Push(Value v) { elements_.push_back(std::move(v)); }
+  size_t Size() const { return elements_.size(); }
+  const Value& At(size_t i) const;
+
+  // Object access. Get returns Undefined for a missing key; Set overwrites
+  // in place (keeping the key's position) or appends.
+  const Members& members() const { return members_; }
+  const Value& Get(const std::string& key) const;
+  void Set(const std::string& key, Value v);
+  void Remove(const std::string& key);
+
+  static bool StrictEquals(const Value& a, const Value& b);
+
+ private:
+  explicit Value(Kind kind) : kind_(kind) {}
+
+  Kind kind_ = Kind::Undefined;
+  bool bool_ = false;
+  double number_ = 0;
+  std::string string_;
+  Elements elements_;
+  Members members_;
+};
+
+// JSON.stringify-compatible for the value shapes the decision layer produces
+// (undefined members skipped, undefined array elements become null, integral
+// numbers within the double-safe range print without a decimal point). A
+// top-level Undefined prints as "undefined" so two undefined results compare
+// equal.
+std::string Stringify(const Value& v);
+
+// Hard limits for Parse. The TS reference has none (JSON.parse is unbounded)
+// and the divergence is deliberate: this parser runs inside the native
+// orchestrators on the raw checkUpdate body, and with sizeof(Value) ~ 96 a
+// 1 MB "[0,0,...]" balloons to ~100 MB of heap. A response over either cap is
+// treated as malformed (HandleCheckResponse -> invalidResponse). Real
+// responses are a few KB and a few hundred nodes.
+constexpr size_t kMaxInputBytes = 1024 * 1024;
+constexpr size_t kMaxNodes = 65536;
+
+// Strict JSON parser (the vectors file and checkUpdate responses). Returns
+// Undefined and sets *ok to false on malformed input; nesting beyond 64
+// levels, more than kMaxInputBytes of text or more than kMaxNodes values are
+// rejected so hostile server data cannot exhaust the stack or the heap.
+// Number parsing/printing is locale-independent (never strtod/LC_NUMERIC).
+// Lone surrogate escapes decode to U+FFFD so the output is always valid UTF-8.
+Value Parse(const std::string& text, bool* ok);
+
+}  // namespace flowjson

package/cpp/update_flow_core/update_flow_core.cpp

@@ -0,0 +1,418 @@
+/**
+ * [INPUT]: 依赖 update_flow_core.h、flow_json 的 JS 兼容语义与 TypeScript golden 向量约束
+ * [OUTPUT]: 实现 Murmur3 灰度、端点排序、check 请求/响应、下载尝试和 forceBoot 激活决策
+ * [POS]: update_flow_core 的无 IO 策略实现，与 src/updateFlowCore.ts 逐行为同构
+ */
+#include "update_flow_core.h"
+
+#include <cmath>
+
+namespace updateflow {
+
+using flowjson::Value;
+
+namespace {
+
+// The low byte of every UTF-16 code unit of `utf8`, which is exactly what the
+// TS reference hashes (`key.charCodeAt(i) & 0xff` over `key.length` units).
+// Identity for ASCII; an astral code point contributes its two surrogate
+// units. Accepts the JNI modified-UTF-8 forms too (C0 80 for U+0000 and
+// byte-encoded surrogates count as one unit each, as charCodeAt would see
+// them); malformed bytes decode to U+FFFD.
+std::vector<unsigned char> Utf16LowBytes(const std::string& utf8) {
+  std::vector<unsigned char> units;
+  units.reserve(utf8.size());
+  size_t i = 0;
+  while (i < utf8.size()) {
+    const unsigned char first = static_cast<unsigned char>(utf8[i]);
+    uint32_t codePoint = 0xfffd;
+    size_t width = 1;
+    if (first < 0x80) {
+      codePoint = first;
+    } else if (first >= 0xc2 && first <= 0xdf && i + 1 < utf8.size()) {
+      const unsigned char b1 = static_cast<unsigned char>(utf8[i + 1]);
+      if ((b1 & 0xc0) == 0x80) {
+        codePoint = ((first & 0x1f) << 6) | (b1 & 0x3f);
+        width = 2;
+      }
+    } else if (first == 0xc0 && i + 1 < utf8.size() &&
+               static_cast<unsigned char>(utf8[i + 1]) == 0x80) {
+      codePoint = 0;
+      width = 2;
+    } else if (first >= 0xe0 && first <= 0xef && i + 2 < utf8.size()) {
+      const unsigned char b1 = static_cast<unsigned char>(utf8[i + 1]);
+      const unsigned char b2 = static_cast<unsigned char>(utf8[i + 2]);
+      if ((b1 & 0xc0) == 0x80 && (b2 & 0xc0) == 0x80 &&
+          !(first == 0xe0 && b1 < 0xa0)) {
+        codePoint = ((first & 0x0f) << 12) | ((b1 & 0x3f) << 6) | (b2 & 0x3f);
+        width = 3;
+      }
+    } else if (first >= 0xf0 && first <= 0xf4 && i + 3 < utf8.size()) {
+      const unsigned char b1 = static_cast<unsigned char>(utf8[i + 1]);
+      const unsigned char b2 = static_cast<unsigned char>(utf8[i + 2]);
+      const unsigned char b3 = static_cast<unsigned char>(utf8[i + 3]);
+      if ((b1 & 0xc0) == 0x80 && (b2 & 0xc0) == 0x80 &&
+          (b3 & 0xc0) == 0x80 && !(first == 0xf0 && b1 < 0x90) &&
+          !(first == 0xf4 && b1 > 0x8f)) {
+        codePoint = ((first & 0x07) << 18) | ((b1 & 0x3f) << 12) |
+                    ((b2 & 0x3f) << 6) | (b3 & 0x3f);
+        width = 4;
+      }
+    }
+    i += width;
+    if (codePoint <= 0xffff) {
+      units.push_back(static_cast<unsigned char>(codePoint & 0xff));
+    } else {
+      codePoint -= 0x10000;
+      units.push_back(static_cast<unsigned char>((0xd800 + (codePoint >> 10)) & 0xff));
+      units.push_back(static_cast<unsigned char>((0xdc00 + (codePoint & 0x3ff)) & 0xff));
+    }
+  }
+  return units;
+}
+
+}  // namespace
+
+uint32_t Murmur3_32(const std::string& key, uint32_t seed) {
+  // The TS reference emulates 32-bit multiplication with 16-bit halves;
+  // native uint32_t arithmetic is exactly (x * y) mod 2^32, so the halved
+  // dance collapses to plain multiplies. Input bytes are the low byte of each
+  // UTF-16 code unit (charCodeAt & 0xff), not the UTF-8 bytes: hashing UTF-8
+  // would bucket non-ASCII keys differently from the TS reference.
+  const uint32_t c1 = 0xcc9e2d51;
+  const uint32_t c2 = 0x1b873593;
+  const std::vector<unsigned char> units = Utf16LowBytes(key);
+  static const unsigned char kEmpty = 0;
+  const unsigned char* data = units.empty() ? &kEmpty : units.data();
+  const size_t len = units.size();
+  const size_t nblocks = len / 4;
+  uint32_t h1 = seed;
+
+  for (size_t i = 0; i < nblocks; i++) {
+    uint32_t k1 = static_cast<uint32_t>(data[i * 4]) |
+                  (static_cast<uint32_t>(data[i * 4 + 1]) << 8) |
+                  (static_cast<uint32_t>(data[i * 4 + 2]) << 16) |
+                  (static_cast<uint32_t>(data[i * 4 + 3]) << 24);
+    k1 *= c1;
+    k1 = (k1 << 15) | (k1 >> 17);
+    k1 *= c2;
+    h1 ^= k1;
+    h1 = (h1 << 13) | (h1 >> 19);
+    h1 = h1 * 5 + 0xe6546b64;
+  }
+
+  uint32_t k1 = 0;
+  const unsigned char* tail = data + nblocks * 4;
+  switch (len & 3) {
+    case 3:
+      k1 ^= static_cast<uint32_t>(tail[2]) << 16;
+      [[fallthrough]];
+    case 2:
+      k1 ^= static_cast<uint32_t>(tail[1]) << 8;
+      [[fallthrough]];
+    case 1:
+      k1 ^= tail[0];
+      k1 *= c1;
+      k1 = (k1 << 15) | (k1 >> 17);
+      k1 *= c2;
+      h1 ^= k1;
+  }
+
+  h1 ^= static_cast<uint32_t>(len);
+  h1 ^= h1 >> 16;
+  h1 *= 0x85ebca6b;
+  h1 ^= h1 >> 13;
+  h1 *= 0xc2b2ae35;
+  h1 ^= h1 >> 16;
+  return h1;
+}
+
+bool IsInRollout(double rollout, const std::string& uuid) {
+  return static_cast<double>(Murmur3_32(uuid) % 100) < rollout;
+}
+
+bool IsMirrorRetryableCode(const std::string& code) {
+  return code != "PATCH_FAILED";
+}
+
+namespace {
+
+// ^[a-z][a-z0-9+.-]*:\/\/ (case-insensitive)
+bool HasExplicitScheme(const std::string& s) {
+  size_t i = 0;
+  auto isAlpha = [](char c) {
+    return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
+  };
+  if (i >= s.size() || !isAlpha(s[i])) {
+    return false;
+  }
+  i++;
+  while (i < s.size()) {
+    char c = s[i];
+    if (isAlpha(c) || (c >= '0' && c <= '9') || c == '+' || c == '.' ||
+        c == '-') {
+      i++;
+    } else {
+      break;
+    }
+  }
+  return s.compare(i, 3, "://") == 0;
+}
+
+}  // namespace
+
+Value JoinUrls(const Value& paths, const Value& fileName) {
+  if (!fileName.Truthy()) {
+    return Value::Undefined();
+  }
+  Value urls = Value::Array();
+  for (const auto& path : paths.elements()) {
+    std::string normalized = path.AsString();
+    while (!normalized.empty() && normalized.back() == '/') {
+      normalized.pop_back();
+    }
+    std::string base = HasExplicitScheme(normalized)
+                           ? normalized
+                           : "https://" + normalized;
+    urls.Push(Value::String(base + "/" + fileName.AsString()));
+  }
+  return urls;
+}
+
+Value OrderEndpointCandidates(const Value& endpoints, double randomSample) {
+  Value deduped = Value::Array();
+  for (const auto& endpoint : endpoints.elements()) {
+    if (!endpoint.Truthy()) {
+      continue;
+    }
+    bool seen = false;
+    for (const auto& kept : deduped.elements()) {
+      // Set membership is ===: a stray non-string entry (a number, `true`)
+      // dedupes against equal primitives only, never against strings.
+      if (Value::StrictEquals(kept, endpoint)) {
+        seen = true;
+        break;
+      }
+    }
+    if (!seen) {
+      deduped.Push(endpoint);
+    }
+  }
+  const size_t n = deduped.Size();
+  if (n < 2) {
+    return deduped;
+  }
+  const double idx = std::isfinite(randomSample)
+                         ? std::floor(randomSample * static_cast<double>(n))
+                         : 0;
+  // Validate in floating-point space before converting to size_t: converting
+  // NaN, infinity, or an out-of-range value is undefined behavior in C++.
+  const size_t first = idx <= 0 ? 0
+                                : (idx >= static_cast<double>(n - 1)
+                                       ? n - 1
+                                       : static_cast<size_t>(idx));
+  Value ordered = Value::Array();
+  ordered.Push(deduped.At(first));
+  for (size_t i = 0; i < n; i++) {
+    if (i != first) {
+      ordered.Push(deduped.At(i));
+    }
+  }
+  return ordered;
+}
+
+Value BuildCheckRequestBody(const Value& input) {
+  Value body = Value::Object();
+  // Caller extras go in FIRST: they may add fields but never override the
+  // identity fields the server keys its decision on (mirrors the TS
+  // `{ ...extra, packageVersion, hash, ... }` spread, including key order).
+  const Value& extra = input.Get("extra");
+  if (extra.IsObject()) {
+    for (const auto& member : extra.members()) {
+      body.Set(member.first, member.second);
+    }
+  }
+  body.Set("packageVersion", input.Get("packageVersion"));
+  // Native callers provide the immutable channel. Keep the same default as
+  // the TypeScript reference when an older native bridge omits the field.
+  const Value& channel = input.Get("channel");
+  if (channel.IsString() && !channel.AsString().empty()) {
+    body.Set("channel", channel);
+  } else {
+    body.Set("channel", Value::String("default"));
+  }
+  body.Set("hash", input.Get("currentVersion"));
+  body.Set("buildTime", input.Get("buildTime"));
+  body.Set("cInfo", input.Get("cInfo"));
+  const Value& diffV = input.Get("supportedDiffVersion");
+  if (diffV.Truthy()) {
+    body.Set("diffV", diffV);
+  } else {
+    body.Remove("diffV");
+  }
+  const Value& bundleHash = input.Get("bundleHash");
+  if (bundleHash.Truthy()) {
+    body.Set("bundleHash", bundleHash);
+  } else {
+    body.Remove("bundleHash");
+  }
+  if (input.Get("isDev").Truthy()) {
+    body.Remove("buildTime");
+  }
+  // Transitional dual form (mirrors the TS side): nested copy of the caller
+  // extras next to the legacy root-level spread.
+  if (extra.IsObject() && !extra.members().empty()) {
+    Value nested = Value::Object();
+    for (const auto& member : extra.members()) {
+      nested.Set(member.first, member.second);
+    }
+    body.Set("extra", std::move(nested));
+  }
+  return body;
+}
+
+Value ResolveCheckResult(const Value& rootInfo, const Value& identity) {
+  Value rootResult = Value::Object();
+  for (const auto& member : rootInfo.members()) {
+    if (member.first != "expVersion") {
+      rootResult.Set(member.first, member.second);
+    }
+  }
+  const Value& expVersion = rootInfo.Get("expVersion");
+  const Value& currentVersion = identity.Get("currentVersion");
+  // expVersion?.config?.rollout?.[identity.packageVersion] — Get on a
+  // non-object returns Undefined, mirroring optional chaining.
+  const Value& rollout = expVersion.Get("config").Get("rollout").Get(
+      identity.Get("packageVersion").AsString());
+  if (rootResult.Get("update").Truthy() && expVersion.Truthy() &&
+      rollout.IsNumber()) {
+    if (IsInRollout(rollout.AsNumber(), identity.Get("uuid").AsString())) {
+      const Value& expHash = expVersion.Get("hash");
+      if (expHash.IsString() && !expHash.AsString().empty() &&
+          Value::StrictEquals(expHash, currentVersion)) {
+        Value upToDate = Value::Object();
+        upToDate.Set("upToDate", Value::Bool(true));
+        return upToDate;
+      }
+      Value info = Value::Object();
+      info.Set("update", Value::Bool(true));
+      for (const auto& member : expVersion.members()) {
+        info.Set(member.first, member.second);
+      }
+      if (rootResult.Get("paths").Truthy()) {
+        info.Set("paths", rootResult.Get("paths"));
+      }
+      return info;
+    }
+  }
+  const Value& rootHash = rootResult.Get("hash");
+  if (rootResult.Get("update").Truthy() && rootHash.IsString() &&
+      !rootHash.AsString().empty() &&
+      Value::StrictEquals(rootHash, currentVersion)) {
+    Value upToDate = Value::Object();
+    upToDate.Set("upToDate", Value::Bool(true));
+    return upToDate;
+  }
+  return rootResult;
+}
+
+namespace {
+
+Value DeclineDownload(const char* reason) {
+  Value none = Value::Object();
+  none.Set("action", Value::String("none"));
+  none.Set("reason", Value::String(reason));
+  return none;
+}
+
+}  // namespace
+
+Value DecideDownload(const Value& info, const Value& identity, bool isDev) {
+  const Value& hash = info.Get("hash");
+  Value paths = info.Get("paths");
+  if (paths.IsUndefined() || paths.kind() == Value::Kind::Null) {
+    paths = Value::Array();  // info.paths ?? [] — a server `null` too
+  }
+  if (!info.Get("update").Truthy() || !hash.Truthy()) {
+    return DeclineDownload("noUpdate");
+  }
+  if (Value::StrictEquals(hash, identity.Get("currentVersion"))) {
+    return DeclineDownload("alreadyCurrent");
+  }
+  const Value& rolledBack = identity.Get("rolledBackVersion");
+  if (rolledBack.Truthy() && Value::StrictEquals(hash, rolledBack)) {
+    return DeclineDownload("rolledBack");
+  }
+  Value attempts = Value::Array();
+  auto pushAttempt = [&attempts](const char* type, const Value& urls) {
+    if (urls.IsArray() && urls.Size() > 0) {
+      Value attempt = Value::Object();
+      attempt.Set("type", Value::String(type));
+      attempt.Set("urls", urls);
+      attempts.Push(std::move(attempt));
+    }
+  };
+  if (!isDev) {
+    pushAttempt("diff", JoinUrls(paths, info.Get("diff")));
+    pushAttempt("pdiff", JoinUrls(paths, info.Get("pdiff")));
+  }
+  Value fullUrls = JoinUrls(paths, info.Get("full"));
+  pushAttempt("full", fullUrls);
+
+  const bool devNoop =
+      isDev && !(fullUrls.IsArray() && fullUrls.Size() > 0);
+  if (attempts.Size() == 0 && !devNoop) {
+    return DeclineDownload("noArtifact");
+  }
+
+  Value decision = Value::Object();
+  decision.Set("action", Value::String("download"));
+  decision.Set("hash", hash);
+  decision.Set("attempts", std::move(attempts));
+  decision.Set("devNoop", Value::Bool(devNoop));
+  return decision;
+}
+
+bool ShouldActivateAfterDownload(const Value& info,
+                                 const std::string& afterDownload) {
+  return afterDownload == "setNeedUpdate" ||
+         info.Get("config").Get("forceBoot").Truthy();
+}
+
+bool IsValidCheckResult(const Value& root) {
+  if (!root.IsObject()) {
+    return false;
+  }
+  const Value& upToDate = root.Get("upToDate");
+  const Value& update = root.Get("update");
+  const Value& expired = root.Get("expired");
+  const Value& paused = root.Get("paused");
+  return upToDate.IsBool() || update.IsBool() || expired.IsBool() ||
+         paused.IsString();
+}
+
+bool IsValidCheckResponse(const std::string& responseText) {
+  bool ok = false;
+  Value root = flowjson::Parse(responseText, &ok);
+  return ok && IsValidCheckResult(root);
+}
+
+Value HandleCheckResponse(const std::string& responseText,
+                          const Value& identity, bool isDev,
+                          const std::string& afterDownload) {
+  bool ok = false;
+  Value root = flowjson::Parse(responseText, &ok);
+  if (!ok || !IsValidCheckResult(root)) {
+    return DeclineDownload("invalidResponse");
+  }
+  Value resolved = ResolveCheckResult(root, identity);
+  Value decision = DecideDownload(resolved, identity, isDev);
+  if (decision.Get("action").AsString() == "download") {
+    decision.Set("activate", Value::Bool(ShouldActivateAfterDownload(
+                                 resolved, afterDownload)));
+  }
+  decision.Set("info", std::move(resolved));
+  return decision;
+}
+
+}  // namespace updateflow

package/cpp/update_flow_core/update_flow_core.h

@@ -0,0 +1,100 @@
+/**
+ * [INPUT]: 依赖 flow_json 值模型、调用方注入的设备身份/随机样本与 src/updateFlowCore.ts 参考语义
+ * [OUTPUT]: 对外提供灰度、URL、请求体、响应解析、下载策略、激活策略和组合处理函数
+ * [POS]: update_flow_core 的纯决策契约，平台编排器只执行其结果而不得重写策略
+ */
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "flow_json.h"
+
+// C++ port of the update-flow decision layer.
+//
+// src/updateFlowCore.ts is the REFERENCE implementation: every function here
+// mirrors its TS counterpart 1:1, including object key order and JS
+// truthiness/strict-equality semantics, because parity is enforced by golden
+// vectors (tests/flow_vectors.json, generated from the TS side). Any semantic
+// change lands in the TS file first, regenerates the vectors, then gets
+// ported here — never the other direction.
+//
+// Like the TS side this layer is pure: no IO, no time, no randomness — the
+// random sample, identity and parsed JSON all arrive as parameters. The
+// orchestrators (per-platform HTTP/download/state glue) own all effects.
+namespace updateflow {
+
+uint32_t Murmur3_32(const std::string& key, uint32_t seed = 0);
+
+// murmur(uuid) % 100 < rollout — the gray-release bucketing predicate.
+bool IsInRollout(double rollout, const std::string& uuid);
+
+// Whether a failed download attempt should move on to the next mirror of the
+// same artifact. Anything but PATCH_FAILED is: every mirror serves the same
+// bytes, so a patch that could not be applied fails on all of them and only
+// the next strategy can help. An absent code (empty string) is retryable.
+// Mirrors isMirrorRetryableCode; covered by the golden vectors so the native
+// orchestrators' retry loops cannot drift from the TS reference.
+bool IsMirrorRetryableCode(const std::string& code);
+
+// paths × fileName -> candidate URL array; Undefined when fileName is falsy
+// (mirrors joinUrls returning undefined without a file name).
+flowjson::Value JoinUrls(const flowjson::Value& paths,
+                         const flowjson::Value& fileName);
+
+// Dedupe + move the sampled pick to the front, rest in configured order.
+// randomSample ∈ [0, 1) is injected by the caller.
+flowjson::Value OrderEndpointCandidates(const flowjson::Value& endpoints,
+                                        double randomSample);
+
+// input: { packageVersion, currentVersion, buildTime, cInfo,
+//          supportedDiffVersion?, bundleHash?, isDev?, extra? }
+flowjson::Value BuildCheckRequestBody(const flowjson::Value& input);
+
+// identity: { packageVersion, currentVersion?, uuid }
+flowjson::Value ResolveCheckResult(const flowjson::Value& rootInfo,
+                                   const flowjson::Value& identity);
+
+// identity: { currentVersion?, rolledBackVersion? }
+// -> { action: 'none', reason } | { action: 'download', hash, attempts,
+//      devNoop }
+flowjson::Value DecideDownload(const flowjson::Value& info,
+                               const flowjson::Value& identity, bool isDev);
+
+// Whether the orchestrator should activate a downloaded version for the
+// next launch: the client's silent strategies opt in locally
+// (afterDownload == "setNeedUpdate"), or the server marks the version
+// config.forceBoot — the per-version remote override that closes the
+// brick-rescue gap for alert-strategy apps (a bricked device never runs
+// JS, so activation cannot wait for it). Native-only; the device-local
+// rolledBackVersion guard in DecideDownload still wins, and the activated
+// version keeps the first_time crash-protection rollback.
+// Schema gate for a checkUpdate response. A valid response is a JSON object
+// carrying at least one verdict field of the expected type: `upToDate`,
+// `update` or `expired` (boolean), or `paused` (string). Anything else — an
+// array, `{"error": "..."}`, an HTML page that happened to parse — is a
+// failed endpoint and must not stop the endpoint fallback. Mirrors
+// src/updateFlowCore.ts isValidCheckResult.
+bool IsValidCheckResult(const flowjson::Value& root);
+bool IsValidCheckResponse(const std::string& responseText);
+
+bool ShouldActivateAfterDownload(const flowjson::Value& info,
+                                 const std::string& afterDownload);
+
+// Composes Parse → ResolveCheckResult → DecideDownload: one call from the
+// raw checkUpdate response text to a download decision, so the platform
+// orchestrators contain no decision logic at all. identity is the union of
+// both composed functions' needs: { packageVersion, currentVersion?, uuid,
+// rolledBackVersion? }. afterDownload is the client's persisted activation
+// policy; a download decision carries `activate` (ShouldActivateAfterDownload
+// folded over it and the version's forceBoot) plus `info` — the resolved
+// check result — so orchestrators can persist name/description/metaInfo
+// alongside a downloaded version (the JS side's setLocalHashInfo).
+// Malformed JSON yields { action: 'none', reason: 'invalidResponse' }.
+flowjson::Value HandleCheckResponse(const std::string& responseText,
+                                    const flowjson::Value& identity,
+                                    bool isDev,
+                                    const std::string& afterDownload);
+
+}  // namespace updateflow