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.
Offer an update without blocking use
Section titled “Offer an update without blocking use”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');}Require a store update
Section titled “Require a store update”First ship the supporting host to users. When retiring hosts below bridge 18:
node valence/valence.mjs bundle --min-host 18node valence/valence.mjs pointer --seq <new-seq> --rollout 100Upload 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.
Withdraw a mistaken policy
Section titled “Withdraw a mistaken policy”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.