soroq_flutter 0.1.10

Flutter plugin and Android runtime bridge for the Soroq OTA platform.

soroq_flutter

soroq_flutter is the Flutter-facing plugin for Soroq.

It bundles the Dart runtime bridge, the Android plugin/bootstrap layer, and the native startup/update wiring that Soroq uses on Android.

What It Includes

• a reusable Dart API for the soroq/engine_runtime method channel
• runtime info, cold-start state, and auto-update state models
• Android startup wiring through a manifest-merged init provider
• native startup/update coordinators and a bundled arm64 Android JNI runtime
• re-exports of the pure Dart soroq_sdk models and client

For the smallest public onboarding flow, start here:

• docs/public-alpha-android-quickstart.md

For Android build-stack readiness, use the repo preflight:

source ../../scripts/engine_env.sh
../../scripts/check_soroq_android_toolchain.sh

The current public-alpha lane is documented in docs/android-toolchain-readiness.md.

Installation

dependencies:
  soroq_flutter: ^0.1.10

This is the latest published package target in this checkout. App teams should use flutter pub add soroq_flutter so pub.dev resolves the latest published plugin. Repository maintainers should run make package-release-train-status and follow its next_step for the immediate publish/proof action; use publish_plan only when the train is staged for release.

Basic Setup

Add a project-level soroq.yaml:

app_id: com.example.app
channel: stable

Import the package from Dart:

import 'package:soroq_flutter/soroq_flutter.dart';

Then use SoroqEngineRuntimeBridge to inspect runtime state, read startup results, and configure auto-update behavior.

Device Patch Status

Apps and dashboards should avoid vague ready or live labels by themselves. Read SoroqEngineRuntimeBridge.getAutoUpdateState() and display:

• state.devicePatchLabel for the lifecycle phase
• state.devicePatchIdentityLabel for the concrete patch number and id
• state.devicePatchDetailLabel for the operator-facing explanation

For example, an active patch can render as Active patch #13 on this device with identity Patch #13 (patch-live-13). A staged patch can render as Staged patch #14 - restart required with identity Patch #14 (patch-staged-14).

For operator handoffs that reconcile hosted patch identity with device state, use docs/operator-patch-identity-handoff.md.

The public CLI flow around this package is now:

soroq init --app-id com.example.app
soroq status --check
soroq app create --name "Example App" --if-not-exists
soroq app list
soroq app status
soroq inspect android --artifact /absolute/path/to/app-release.aab
soroq release android
soroq release list --app-id com.example.app
soroq release status --release-id my-release
soroq patch android
soroq patch config --config-file /absolute/path/to/config.json --release-id my-release
soroq patch list --app-id com.example.app --channel stable
soroq patch status --patch-id my-patch
soroq patch health --patch-id my-patch
soroq rollback --patch-id my-patch

soroq status should show release ready: yes and patch ready: yes before you run the release or patch commands. Those commands use the same local project preflight and will stop early if app_id, channel, or the package dependency shape is invalid. Add --check to make that readiness check fail CI or local scripts until the project is ready.

The short release command runs flutter build appbundle --release, discovers the Android artifact from the usual Flutter output directories or release-candidates/, then records an immutable copy under .soroq/releases/.... The short patch command runs the same release build, uses that recorded base, and discovers the newest compatible candidate artifact. Explicit --artifact, --base-artifact, --candidate-artifact, --release-id, and --build=false remain available for CI and unusual build layouts. Flutter build flags can be passed after --, for example soroq patch android -- --flavor internal --dart-define=API_ENV=prod.

Config Patches

Because this package re-exports soroq_sdk, Flutter apps can consume hosted JSON config patches without manually reading the patch bundle:

final client = SoroqControlPlaneClient(
  baseUrl: Uri.parse('https://your-soroq-control-plane.example'),
);
final configPatch = await client.fetchConfigPatch(
  const SoroqPatchCheckRequest(
    appId: 'com.example.app',
    runtimeId: 'runtime-fingerprint',
    currentPatchNumber: 0,
  ),
);

if (configPatch != null) {
  final config = configPatch.config;
  // Store configPatch.patch.number after your app accepts the payload.
}

Config patches are download_only: Soroq delivers and parses the payload, then your app chooses how to apply it.

What Is Proven Today

• Android cold-start bootstrap through the shared plugin/runtime layer
• hosted patch-check and boot-report flows
• staged asset/config OTA on the Android public-alpha lane
• hosted release/AOT code patching for supported Soroq-compatible Android artifacts
• runtime_managed_dart protocol/model support for the continuing runtime-managed research lane

Compatibility Truth

This package is not a claim of universal stock-Flutter compatibility yet.

The current real OTA lanes are validated against a Soroq-compatible pinned Flutter toolchain, including tracked Flutter framework/engine patch seams in this repository. If a team is on a different Flutter version, they should use an explicitly supported Soroq toolchain release rather than assuming arbitrary cross-version compatibility.

In practical terms:

• the pure Dart control-plane layer is easier to share broadly
• the Android plugin/runtime layer is more version-sensitive
• the full OTA shipping path currently depends on Soroq-maintained Flutter fork/patch alignment

Status

This package is part of the current Soroq Android public alpha. It is real and proven on Android, but the broader product is still being hardened toward a more Shorebird-like developer experience. The public package should be described as Android asset/config OTA plus supported release/AOT code patching and control-plane/runtime infrastructure today. Arbitrary stock-Flutter version support is tracked through the Soroq compatibility matrix instead of being assumed automatically for every Flutter toolchain.

Published Consumer Proof

Repository maintainers can verify from the repository root that pub.dev consumers are not relying on local path dependencies:

make package-post-publish-proof

That target checks published package versions and archive freshness, then creates fresh Dart and Flutter apps, installs soroq_sdk and soroq_flutter from pub.dev, imports the public APIs, runs Flutter analysis, builds an Android debug APK from the published plugin, and finishes the non-device public-alpha readiness proof.

Because it installs from pub.dev and finishes the public-alpha readiness proof, it requires network access to pub.dev and the hosted Soroq public-alpha services after both packages are published.

Local Repo Development

This repository may use a local pubspec_overrides.yaml while developing both packages together. Published consumers should depend on the pub.dev package versions, not the local override.

The published Android plugin bundles the arm64 Soroq runtime JNI library so a fresh Flutter app does not need this repository's runtime/ checkout just to build. Repository maintainers can force a local Rust rebuild with SOROQ_BUILD_RUST_JNI=1. The Gradle rebuild path remaps local filesystem prefixes out of Rust diagnostics so regenerated JNI artifacts do not leak developer machine paths into the package.

Internal Proof Helpers

For repository-local validation, the repo still includes the existing proof helpers:

source ../../scripts/engine_env.sh
../../scripts/verify_zero_touch_consumer_app.sh

source ../../scripts/engine_env.sh
../../scripts/verify_zero_touch_consumer_aot_code_patch.sh

source ../../scripts/engine_env.sh
../../scripts/verify_zero_touch_consumer_aot_rollback.sh