Skip to content
Valence is in beta. The bundle format and update protocol are meant to stay stable; the CLI, the generated code and the two runtime packages’ APIs may still change. What beta means

Forcing an update

A release that needs a newer native host can now say so separately from corrupted bytes. This follows contracts 2.3, 2.5 and 4.6. iOS remains experimental and untested.

Ship the new store build first, wait until it is available, then cut an OTA release. requires.bridge remains the minimum bridge needed to execute that UI. A supporting host reports reason: "needsStoreUpdate" and requiredBridge when it is too old. The existing signed UI keeps working. Signature, identity, sequence, floor, metadata and file failures continue to mean rejected.

To opt in, add nullable requiredBridge: "int?" and minHost: "int?" to your BundleStatus type; declare app.openStore with since at or above 17 — use your schema’s next version number, not the literal 17; no params, returns: "void"; increase your own schema above its last store baseline (at least 17), regenerate and ship a store build. Do not change existing method shapes or since values.

17 is the reserved number: the minimum at which the package implements app.openStore for you instead of generating an abstract handler. It is a floor, not the number to write. If your last store baseline is already 18 or higher, since: 17 is refused by the additive-only rule — method "app.openStore" is new since the store build, so it needs since > 18 … and at least 17 to use the package's implementation — and that refusal reads like “the package has not shipped this yet”, which sends you off to write native code you do not need. Read every built-in since in a guide as a floor and take the higher of it and your own next version. Then confirm the delegation in the generated Dart: bridge.g.dart should contain await valence.openStore(); inside ValenceBuiltins, not an abstract member on BridgeHandlers. app.info().builtins >= 17 identifies the new runtime revision; older schemas without requiredBridge keep the legacy rejected reason. A new declaration does not upgrade a previously installed runtime.

const status = await call('bundle.status');
if (status.reason === 'needsStoreUpdate') {
// Show an update prompt, and call this from the user's button:
if (has('app.openStore')) await call('app.openStore');
}

First ship the supporting host to users. When retiring hosts below bridge 18:

Terminal window
node valence/valence.mjs bundle --min-host 18
node valence/valence.mjs pointer --seq <new-seq> --rollout 100

Upload files, signed manifest and signature, then the pointer last. minHost is a positive integer in the signed manifest. It is the app’s generated host bridge version, not Valence’s package version or Android version. It is separate from the bundle’s UI compatibility requirement; a pinned --requires-bridge 17 can coexist with --min-host 18. A built-in cannot demand a version above its own host.

Once an eligible supporting host verifies a policy above its version, it shows a native Update required screen with Open store and Check again, replacing the web view. It retains users’ rows and queued edits. A pending/trial bundle is not consumed and blocking does not count a failed trial. Exact signed policy bytes are cached and verified on restart, so a network failure does not remove a block. BundleStatus.minHost retains that policy even when the last attempt is offline.

A block discovered mid-session takes the page down rather than hiding it: the web view controller goes, and so does the loopback server that was serving the bundle on 127.0.0.1. The host also forgets that server, which matters because of an unrelated rule — iOS can reclaim a listening socket while an app is suspended, so the host rebinds any server whose liveness probe fails when it comes back. A deliberately closed one that was still being tracked looked exactly like a reclaimed one, and the next return from the background put the bundle back on the port behind the blocking screen. It does not any more, and a block now survives backgrounding with the port still closed.

Android’s destination is fixed from the compiled application ID at https://play.google.com/store/apps/details?id=<appId>. A page and the manifest cannot choose another URL. For iOS configure "store": {"iosAppId": "123456789"} in valence.config.json before codegen; without it app.openStore returns E_UNSUPPORTED. Launch failure returns E_INTERNAL and the native screen allows a retry. iOS is experimental and untested. No Play account, store publication or remote device upgrade has been verified by package tests.

Sign a higher sequence release omitting --min-host, or using a lower value, and publish its pointer. A verified newer manifest supersedes the previous policy. Changing the unsigned pointer alone, replaying an older signed manifest, a bad signature, malformed metadata or an offline request cannot clear it. The host’s Check again button discovers a signed withdrawal and recreates the web page. Upgrading the host to a sufficient bridge version also unblocks use.

--min-host does not carry forward, and --floor does. That is deliberate — omitting it is how you withdraw a mistake, so it cannot also be what preserves one — but it means your next ordinary bundle with no flags unblocks everyone the previous release was holding at the store. For a security-motivated requirement that is the release lapsing by accident, so the build warns, names the number the last release signed, and tells you to pass --min-host N again to keep it.

A held pointer can keep a device on a block you have withdrawn. The policy itself is signed, so nobody can author one for you, but the unsigned pointer still decides which signed release a device evaluates. A device that never receives the withdrawal — a cached CDN edge, a pointer that stops advancing, an OTA host under someone else’s control — stays blocked, offline and across restarts, until it sees a higher signed manifest. There is no freshness bound on a policy in 0.4. So sign --min-host only when you are sure, and if you do withdraw one, check that the pointer really moved.

This is an availability policy with consequences: do not require a store build that users cannot install yet. Staged rollout still controls discovery; an offline phone that has never received the policy cannot be forced, nor can an older runtime that ignores minHost. This is not a replacement for server-side authorization or store review. Data and the outbox are retained throughout.

Check the store listing id before you need it. The Android destination is built from your Valence appId, while the Play listing is keyed on the Android applicationId in <host>/android/app/build.gradle.kts. Those are two independently editable values, and if they differ the only button on the blocking screen opens a listing that does not exist. valence doctor has a store listing row that compares them and fails when they differ. Nothing writes applicationId for you: flutter create derives it from --org and the project name, so set it to your appId by hand. On iOS, set store.iosAppId or app.openStore answers E_UNSUPPORTED and the screen has no button at all. Android is tested; iOS is experimental and untested.

Last updated: