valence 0.4.0-beta.1
valence: ^0.4.0-beta.1 copied to clipboard
Flutter host runtime for Valence. Signed over-the-air web UI, offline-first SQLite with sync, and a typed bridge from one schema.
Changelog #
0.4.0-beta.1 - 2026-11-22 #
When the built-in bundle is missing from the app's assets, the startup error now says to declare assets/valence/builtin/ and builtin/files/ in pubspec.yaml, instead of leading with requires.bridge. The package description is shorter, to fit pub.dev's limit. Android hosts still need core library desugaring; valence codegen now writes it for you. See the release notes.
0.4.0-beta.0 - 2026-11-21 #
The first public beta. Android is supported; iOS is experimental and untested. See the release notes for a summary and the known limits.
the startup phases now say what they normally cost #
The per-phase breakdown Valence.open logs gains a description of what each phase does, so a
duration has something to be judged against. binding is in-process; state reads state.json;
store opens SQLite and may migrate; and the remaining five — directories, links, push,
services and notifications — each cross a platform channel. seed is not free after the first
launch: it loads the whole seed asset before it can test its completion stamp, so only the import is
first-launch-and-after-an-upgrade. links is skipped entirely with no link origins, and the one-off
cost then lands on directories. The plugin phases carry a one-off registration cost on
the first launch after an install that is not proportional to what the app declared: on one device,
links was 2292 ms of a 3268 ms first open for an app with a single custom-scheme origin and no App
Links. Nothing changed in the host; the numbers were always these. Startup
diagnostics
the took the lease log line now dates the take-time it recorded #
The line is written after the time it records — the row insert, the commit and the hops back out
all sit in between — so bracketing took the lease and released the lease in logcat
understated the hold. On a device, 91 ms between the two lines around a hold the host correctly
reported as heldForMs=3039. It now reads
sync: took the lease kind=foreground pid=1234 (dated 2951ms ago): subtract the trail from the
line's own timestamp and you have the take-time every heldForMs is measured from, so the pair
brackets the number. The trail is not the database wait — the clock is sampled after that wait on
purpose, which is the fix below — and the store's waiting line remains the instrument for it.
Floors at zero, and it cannot cost an acquisition that has already committed: a clock that throws
while being read for the trail logs a zero. Nothing in your app changes; rebuild the native host.
a sibling isolate's live sync lease is no longer taken over as "future-dated" #
Two syncs could run over one database. acquireLease sampled the clock before opening its
transaction, and BEGIN IMMEDIATE waits for whatever the other isolate is writing — so on a contended
device the transaction could start seconds after the call, and the lease renewal it then read was newer
than its own now. The row looked future-dated, §5.6's clock-skew rule treated it as expired, and a
foreground run took the lease from a background sync that was still working. It also wrote that stale
now back as its own take-time, so the next reader was told an age seconds too old. Both numbers came
from one line.
On a device this hit the first two launches after a clean install, logging
taking over a lease (kind=background, written -11080ms ago): dated in the future, so the clock moved
against a clock sampled every four seconds for 48 seconds that never moved backwards, and ending with
both holders logging released the lease three milliseconds apart.
Three changes. No API, no schema, no change to acquisition, renewal, release or the TTL itself:
- the clock is sampled inside the transaction, after the wait —
store'swaitingline forsync.acquireLeaseis how long that wait was; - a lease row this process wrote counts as held on either side of
now, until it is further ahead than the two-minute TTL. A pid that is ours means a sibling isolate that is running, so the TTL is not the instrument for it; beyond the TTL the clock really has moved and the row is freed, so a backwards clock cannot park sync indefinitely.ValenceSyncStatusandacquireLeasestill read one predicate; - nothing reported as an age can be negative. A displaced row ahead of
nowlogsdated <n>ms in the futureand names the TTL it exceeded;ValenceSyncStatus.leaseAgeMsfloors at 0.
Hosts need no change. If you added a retry or a guard around a foreground sync because two runs appeared to overlap, you can drop it.
a launch destination pre-empts the restored route #
prepareRestoration loaded whatever route the OS snapshot carried, so a cold start that also carried
a launch intent — a pending link, a tapped notification captured by Valence.open, or a tapped push
message — rendered the stale screen before the page could apply the destination the user chose. §6.3
makes the page the arbiter across launch sources, and the restored route was a third source it could not
see, applied by the host before it ran.
It now checks the three mailboxes between activate and the first loadRequest and, when one holds a
destination, drops the route and logs the source:
restoration: a <link|notification|push> launch destination pre-empts the restored route <route>; starting at / and keeping the saved draft
New API, all additive: ValenceRestoration.preemptRoute(), Valence.launchDestination,
ValenceLinks.hasPending, ValenceNotifications.hasInitial and ValencePush.hasInitial. The three
peeks read without consuming, so link.initial() and notify.initial() still answer the page once
each. Only the route goes: state.restore() keeps returning the saved blob, since nothing about a
tap says to discard the user's draft. The account and seq rules in §4.8 run first and still drop both
halves on their own terms, and a start with no launch destination restores its route unchanged.
retain committed sync pages across a later database lock #
A sync interrupted after committing a page now reports that page in its changed
count and buckets, even if the next page or lease renewal locks. Locks taking the
lease remain busy; locks during work remain incomplete results, with earlier
authentication and offline outcomes retaining precedence. Cleanup preserves a
primary non-lock error and its stack; a non-lock cleanup error still surfaces.
A release-only lock retains the completed result, and so does a lock on the
final pendingWrites read, which reports 0 pending rather than discarding the
classified result — ValenceSync.run does this itself, so a page gets it as
well as Valence.backgroundSync, whose own backstop reports zeros.
No lease timing, schema,
package version or host migration changes.
the lease age is measured from acquisition, not from the last renewal #
ValenceSyncStatus.leaseAgeMs, and the heldForMs= a refused run logs, were computed from the
valence.sync.lease row's timestamp. renewLease rewrites that row after every applied page, so the
reported age fell back towards zero on each page and two reads during one continuous hold could
decrease — while releaseLease, which measures from an in-memory take-time, was correct. A reader in
the other isolate has no such take-time, so the row now carries it: valence.sync.lease grows a fourth
field (<epoch ms>:<pid>:<kind>:<taken at>), renewLease passes it through unchanged, and the first
field keeps its old meaning as the last renewal, which is what the TTL is judged against. The reported
age and the release line are now the same measurement.
Additive, like the fields before it: a row written by an earlier host reads back with the take-time absent and reports the row's age, which is the previous behaviour. A take-time the device clock has moved past does the same, so the age is never negative. Acquisition, expiry, the takeover rules and the two-minute TTL are unchanged.
handleReady requires the running document to belong to the trial #
ValenceApp.handleReady tested trial != null && serving == trial && manifest.seq == trial — all by
seq, all set by ValenceUpdater.applyUpdate before reloadPage() awaits the load. The outgoing
document dispatches across that await, so a ready() from it committed a bundle that never rendered.
_onPageStarted now records the bundle-swap count the document started at, and handleReady commits
only while it still matches _swaps — the same mechanism §5.5.1 already uses to recognise a rollback's
own document. The ready timer cannot serve as that signal: it is armed for the trial being replaced and
nothing stops it in between.
countFailure is split so the ready timeout can take and persist its decision before the §5.5.1
drain rather than after it: giveUpOnTrial(seq) is the synchronous half, dropGivenUpCaches(seq) the
asynchronous one. Both take the seq, because applyUpdate can promote a different trial across the
drain and must not inherit the strike. The UI-start callers keep calling countFailure unchanged.
ValenceSync classifies a locked database itself #
run now answers busy for a lock taking the lease (nothing attempted) and failed for one after it,
with the real buckets/changed counters, instead of letting either escape. Valence.backgroundSync
keeps a narrow backstop for a lock around the run — releasing the lease, reading the outbox count — and
no longer guesses at a classification only run can make. A releaseLease that throws no longer
discards the result, and logs that the row stands until the §5.6 TTL expires it.
ValenceUpdater's step-7 holder lookup is best effort, so a lock meeting it does not swallow the stop.
giving up on a trial clears serving before it awaits anything #
ValenceApp._onReadyTimeout cleared serving only once ValenceUpdater.countFailure ran, which is
behind blockCacheWrites() — an async call that returns to the event loop even with no admitted write
to drain. handleReady tests exactly trial != null && serving == trial, and the given-up page keeps
dispatching, so an app.ready() landing in that window committed the expired trial, raised the floor and
counted no failure (the timer was already stopped, so the resumed timeout found no trial). The clear now
happens in the same synchronous step as the decision. countFailure still clears it for the UI-start
callers, which reach it with nothing awaited in front of them.
§2.4 states the rule as "giving up clears serving before the host awaits anything", so the next change
on that path knows why the order matters. The interleaving itself has no test and §8 says so: the ready
ticker is a real timer while the only lever that holds the drain open is a competing SQLite writer, and a
flaky test in the rollback path is worse than a named gap.
a locked database mid-run no longer fails the WorkManager job #
Valence.backgroundSync already answered reason: busy for a locked open. A lock that surfaces once
ValenceSync.run is going now returns reason: failed with a log line instead of throwing — failed
rather than busy, because the lease was taken and buckets may already have been pulled, so "nothing was
attempted" is a claim this path cannot make. Non-lock errors still propagate to the job.
ValenceUpdater's step-7 lease refusal now logs holder= and heldForMs=, so a launch whose OTA did not
install names what held the store. Lease acquisition, expiry and pre-emption are unchanged: §5.6 explains
why displacing a holder mid-transaction is not available.
a rollback that cannot serve its replacement logs it #
ValenceApp's ready-window timeout drops the trial's cached rows, blocks the given-up page's
data.cache writes and then serves current. A failure in that last step — no servable manifest, a
socket that will not bind — used to escape the periodic timer as an unhandled async error. The host
now catches it and logs rollback: serving current after the given-up trial <seq> failed: <error>; the page stays on screen and data.cache stays closed.
Observable behaviour is unchanged: the block stays up, because there is no replacement document to
release it and the given-up page is still dispatching. §5.5.1 said so already; it now says it in the
log as well, and app_widget_test.dart covers both the failed swap and a self-navigation by the
given-up page, which must not release the refusal either.
a pulled row with a negative usn is refused #
ValenceSync's row decoder now requires u >= 0, so a pull page or static chunk carrying a negative
update sequence number is undecodable and leaves the run incomplete instead of writing a kv row.
The reason is the read union, not the wire: it reports usn: -2 for a data.cache overlay and -1 for a
pending write, and those two numbers are the only way a page can tell a local-only row from one the server
vouched for. A pulled row at -2 would be a server row indistinguishable from the page's own cache, so a
retention rule written against §5.5.1 would delete rows it does not own, and native code reading
provenance from kv could not separate them either. The incremental path already refused it through the
strict-ascending-USN check; the static variant takes max_usn from the index rather than from the rows and
had no such check, so the bound belongs in the decoder where both paths pass through it.
No change for a conforming server: a USN counts from 1.
the REST cache has no ceiling, and the package now says so #
No behaviour change in this package: ValenceStore.cache still caps one encoded value at 65,536 UTF-8
bytes and still bounds nothing else — not the row count, not the total bytes, not their age. What changes
is that the absence is documented where it is implemented rather than only implied by a half-sentence in
the spec: a page that never prunes fills the device, and clearing app data is the user's only remedy,
which also takes their synced rows and their unsent writes with it.
The upgrade, for whoever carries a database migration next: a compiled per-bucket maxRows or one
cacheMaxBytes, evicting the oldest write first. The cache table is WITHOUT ROWID and keyed by
(bucket, schema, key) with no written-at column, so "oldest" does not exist yet. See contracts §5.5.1
and the REST cache guide.
a busy sync can say who is holding it #
ValenceSyncStatus gains leaseKind and leaseAgeMs, and the valence.sync.lease row grows a third
field — <epoch ms>:<pid>:<kind>, with foreground, background or push. Appended, so a row from an
earlier 0.4 host and a 0.3 row both still parse. ValenceSync takes a kind:, defaulting to
foreground; Valence.backgroundSync takes one too, defaulting to background, so a push transport
passes ValenceSyncKind.push. The two status fields are non-null on exactly the predicate
acquireLease refuses on, from one shared helper, so a lease this host would take over reports free.
A held row with no kind reports unknown rather than free.
The log carries the same facts: a refused run prints holder=, heldForMs= and its own refused= kind
(once per refusal, not per retry); each run prints taking and releasing the lease with how long it was
held; and backgroundSync brackets its whole run with entered / left. A took with no released,
or an entered with no left, is a lease a torn-down isolate never gave back — a WorkManager
cancellation runs no finally — so a leak is a missing line rather than an inference from a later
busy. Lease acquisition, renewal and expiry are unchanged.
app.info().builtins is now 20. Startup
diagnostics.
four fixes from two independent reviews #
- A sign-out or an account switch can no longer be undone by a response already in flight. An
http.requestbegun as one user could deliver itsSet-Cookieafter that user signed out, which refilled the cookie jar the sign-out had just emptied — in memory, and in the Keystore oncesessionCookieDayswas on — so the next request carried the previous user's session beside the new user's bearer token. Each request now carries the jar's generation and a response whose generation has moved on has its cookies dropped. Your page still receives the response. - A renderer recovery in the background no longer spends a trial's strike. The ready window counts foreground time and is stopped by the pause transition, so a page loaded after the app was already backgrounded started a clock nothing would stop: background time then exhausted the window and counted a failure against a release that was never on screen. Such a page arms the window and the resume starts it.
- A bundle being rolled back cannot refill the cache on its way out. Giving up on a trial drops
every
data.cacheoverlay, but the failed page is alive through the rest of the rollback, so a late REST response could write its shapes straight back for the previous bundle to read. From just before the drop until the replacement page starts,data.cacheanswersE_DENIEDand says why. codegenno longer throws on a payload field named after anObjectmember. An event declaringconstructorortoStringwas accepted and then crashed the generator — and the additive-only rule left no way to remove the field.
two confusing numbers, named properly #
- A built-in's reserved revision is not the
sinceto declare, and the docs now say so wheredata.cacheis introduced: declaremax(18, your next schema version), which is whatcodegencomputes for you. The refusal that follows a changed built-in now tells you to restore the recordedsinceinstead of offering a.v2rename, which for a reserved name would quietly make you reimplement a package feature. - A cache-enabled bucket is still pulled. Declaring a bucket purely to hold REST overlays makes
the device ask your sync server for it on every sync, and a
404there makes the whole run reportfailedand stops sync freshness advancing — the other buckets' rows still arrive, but your page is told the sync failed. Serve overlay-only buckets as an empty page. Said on the REST cache guide, the config reference and in the spec.
response size grants #
Optional compiled http.maxBodyBytes accepts 1..262144 decompressed response bytes (default 65536). Regenerate and ship a host for larger REST responses. Request and escaped reply limits stay unchanged; doctor reports both limits.
bounded session-cookie persistence #
- Native
http.cookieJar.sessionCookieDaysopts into 1–30 days for session cookies across restarts. Off by default; run codegen and rebuild the host. Deadlines never renew on reload; sign-out and account-switch clearing still apply. Guide.
inspect the WebView in debug builds #
A debug build now enables Android WebView inspection, so chrome://inspect shows the page with full DevTools. Profile and release never do (contracts §3.1).
explicit update checks and completed-check notifications #
- Schema 19 adds explicit
bundle.checkandbundle.checkedcompletion, including offers needing a newer store host. Regenerate and rebuild to opt in; pending-onlybundle.updateReadyis unchanged.
an optional host-held cookie jar for one compiled origin #
ValenceConfig.cookieJar(ValenceCookieJar) opts one origin into a host-held jar (contracts §4.5.1). Null by default, and null means exactly today's behaviour:ValenceHttpsends noCookie, discards everySet-Cookie, and touches secure storage only to notice there is nothing to revoke. The origin is compiled fromhttp.cookieJarbyvalence codegen, which refuses one that is not also inhttp.origins, a cleartext non-loopback one, and a mirrored CSRF header the host already controls.ValenceCookiesholds the jar for the runtime's lifetime, so one secure-storage read serves every request. It is host-only byDomain, matchesPathper RFC 6265 §5.1.4, prefersMax-AgeoverExpires, caps at 16 cookies / 4096 bytes each / 8 KiB total, keeps a session cookie in memory only, and persists an expiring one at the reservedvalence.http.cookieskey, whichsecure.getcannot read. A malformedSet-Cookie, an over-cap cookie and unwritable storage are logged, never thrown at the page.Valence.cookies.clear()runs on every path that clears the bearer token:authSetToken(null), including the sign-out of a host that recorded no account and therefore clears no rows, and the §5.3 account switch, inside the sync lease and before the new token is written.Valence.openrevokes a jar the build no longer grants, reading first and writing only when there is something to delete. It never fails the open: a stored jar that cannot be deleted seals the jar for that launch — it sends and absorbs nothing — and an unreadable Keystore reads as absent like every other §4.4 read, so the jar runs in memory.- An independent review of the new write path found two MEDIUMs and eight LOWs; all are fixed. The
clear now runs before the token writes on both the sign-out and the switch path, so a Keystore
that cannot delete the jar fails the sign-out with the user still signed in rather than leaving their
session for the next adoption to inherit.
ValenceCookiesvalidates its own origin — HTTPS unless loopback, exactly normalised, present inhttpOrigins— and seals rather than replaying a credential in the clear for a hand-written config.csrfValueis path-matched likeheader.Secureis dropped over the cleartext loopback carve-out. A natural expiry is written through. The caps are applied on the reload from storage, an envelope with no recorded origin is revoked rather than adopted, the load is memoized as a future rather than a flag,ownsrefuses a URL with no origin to compare, and the post-token header-limit refusal names no size, so it cannot be used to measure credentials. ValenceHttp.hostControlledis now public, and the CSRF mirror is checked against it: a configured header the host already sets throwsE_INTERNALrather than silently overwriting the bearer token or the jar's ownCookie. The CLI refuses the same names, and the two lists are on independent release trains, so this is the backstop that makes a drift loud.
three host fixes from an independent review #
- A blocked host no longer rebinds its loopback server.
Valence.unbound()forgets the server and the manifest when a mid-sessionminHostblock takes the page down, soValenceApp's resume — which rebinds any server whose liveness probe fails, because iOS reclaims listening sockets during a suspend — cannot mistake a deliberately closed server for a reclaimed one and put the bundle and the/_host/routes back on127.0.0.1behind the block. - The update check is coalesced across its five triggers. Start-up, resume, the
foreground ticker, a connectivity report and the blocking screen's "Check again" each ran
the whole transition, so two overlapping checks after a signed withdrawal ran
activateForUiStarttwice — the second reading the first's ownservingas a previous crash and spending a §2.4 trial attempt — and bound a second server, ticker and connectivity subscription with the first of each leaked. - A trial the host gives up on takes its
data.cacheoverlays with it.ValenceUpdater.countFailureclears the cache table on both strikes, not only the one that marks a bundle bad, because one strike already putscurrentback on screen. A cache key is versioned by nothing a rollback moves, so the reverted bundle was reading values in the failed one's shape. Server rows, bucket cursors and the outbox are untouched.
cache selected REST responses offline #
Revision 18 adds data.cache behind a compiled per-bucket cache grant.
Regenerate and ship a store host to opt in. Cached values are disposable overlays
with no server cursor or outbox; pulls replace them and recorded account changes
clear them. Existing synced rows and pending writes survive database migration 3.
Read the guide before using
account data or changing bucket schemas.
renderer loss is recovered from where the platform reports it #
ValenceApphandles anonWebResourceErrorof typewebContentProcessTerminated: it stops the ready timer, reloads the same manifest at the current restoration route, and emits nothing to the page. It counts no §2.4 trial failure — the timer for the dead page used to time out and spend a strike on a release the device's memory pressure had killed. Capped at three recoveries per launch, after which the host drops the controller (leaving the widget tree is not teardown; the controller owns the native WebView) and clearsservingso §2.4 step 2 does not spend the strike on the next UI start either, whiletrialstays set for that launch to retry.- A resume that reclaims the same loopback port now reloads the page when none is loaded. One iOS suspend can take the socket and the content process together, and the old "keep the page" branch left the user on "cannot open page" for the rest of the session.
- Android is unchanged and cannot be fixed here.
webview_flutter_android4.14.1 (newest, checked 2026-11-01) exposes noonRenderProcessGone, so Chromium kills the host process before any Dart code runs — and because no Dart code runs,servingsurvives and the eviction does spend a trial strike. Contracts §3, "Renderer loss", states both with the logcat evidence; a test fails as soon as the plugin exposes the callback.
E_OFFLINE, E_TIMEOUT, and corrections to the store-update policy #
http.requestanswersE_TIMEOUTfor its 20-second deadline andE_OFFLINEwhen the OS reports no network interface, keepingE_INTERNALfor a captive portal, a firewall or a server that is down — the cases it cannot honestly tell apart.ValenceHttptakes an optionalonlinecallback; with none, the behaviour is unchanged. EveryE_TOO_LARGEnames the observed size and the limit, the streamed one as a floor.valenceStoreUrlmatches the platform case-insensitively. The runtime passesdefaultTargetPlatform.name, which Flutter spellsiOS, so the iOS branch was unreachable on every iOS device andapp.openStoreansweredE_UNSUPPORTEDwith a validstore.iosAppIdconfigured.- A store policy discovered mid-session now disposes the WebView controller and closes the loopback server, instead of only removing the view from the widget tree while the page kept running behind the blocking screen.
- The signed policy envelope is persisted only while a policy applies. A withdrawal is recorded as the verified seq alone, so an install with no policy performs no signature verification during startup while a replayed older policy is still refused.
custom notification event adapters #
Regenerated config declares compatible notification events/fields, so the native service cannot
emit its integer-ID payload over a pre-11 app-owned event. Valence.open accepts a native
notificationEventAdapter returning a generated event script or null. It replaces automatic warm
emission and keeps startup buffering; cold access remains consume-once for explicit conversion.
Adopters must regenerate and ship a store build, preserving shipped schemas and baselines.
hasNotification is required, and sync's waits name a lock #
Breaking for hosts with their own ValencePushTransport. ValencePushMessage's hasNotification
is now a required argument with no default. Hosts using valence_push are unaffected — it already
passes message.notification != null. false is the permissive answer, because it is the half of the
data-only check that lets a payload trigger a sync, and core no longer derives it now that the transport
belongs to the host. The default meant a transport that never considered the field turned every
notification carrying {"valence":"sync"} into a background sync; omitting it is now a compile error.
Sync's own lease transaction and observation write go through the same wrapper as the store's queries, so
a confirmed SQLITE_BUSY on either is labelled store: database locked operation=sync.acquireLease
rather than only timed (§5.1.1). No SQL, bind argument, bucket, key or path is logged, as before.
An app-owned method under a built-in's name that differed only in its return type is accepted again:
the generator's signature comparison looked only at the params, so every structured-return built-in
matched and notify.pending returning string[] was refused, against §6.5.
Firebase is an opt-in native package #
Core-only Valence hosts no longer depend on Firebase. Remote push hosts must add
valence_push: ^0.4.0-beta.0, import package:valence_push/valence_push.dart and
replace ValencePush() with createFirebasePush() after Firebase initialization.
Keep direct Firebase dependencies when importing their APIs. Rebuild the native
host; an OTA cannot install or remove SDKs. Custom transports now exchange
ValencePushMessage rather than RemoteMessage and preserve hasNotification.
The Firebase-specific ValencePushMessage.fromRemote constructor is removed;
custom transports construct the provider-neutral record directly.
Bridge schema/signatures, background sync, notification data, caps and consent
rules are unchanged. Local notifications and badges remain core dependencies;
Android desugaring is still needed for local notifications. The core example has
no Firebase dependency, and VALENCE_PUSH=true no longer enables it: follow the
remote-push guide to add the native package and initialization. Firebase's iOS
15.0 minimum applies to push hosts. Device delivery still needs a Firebase project;
iOS is experimental and untested. This supersedes the earlier SDK-disclosure
mitigation below. Audit other app dependencies and final binaries independently.
pendingIds(), because a full reminder queue cannot be read back #
ValenceNotifications.pendingIds() returns the native pending queue's IDs as List<int>, from the
same snapshot pending() reads. Schema 16 delegates notify.pendingIds to it.
pending() carries each request's title, body and payload, capped at 256, 4096 and 4096 bytes, so a
full queue of 64 maximum-size requests is about 540 KB — over the 256 KB bridge reply cap, which
means replyOk answers E_TOO_LARGE. That broke the documented cancel-and-refill-by-difference
workflow on exactly the apps that keep the most reminders queued. pending() is unchanged: trimming
its fields would have made an absent body and an empty one the same answer on the method whose whole
purpose is reconciliation.
A host whose notification service could not start returns an empty list from both.
AppInfo.builtins is now 16.
startup timings and named database waits #
Native startup reports phase entry, completion and elapsed milliseconds through the existing logger. Database operations still pending after ten seconds name their operation and report completion or failure. No schema or app configuration change is needed; ship an updated Flutter host. These diagnostics preserve retries, transactions and user data. They provide evidence for a recurrence and do not establish a cause or fix for earlier Android stalls.
say which SDKs every Valence binary carries #
The docs said a host that does not configure push needs no Firebase. That is true of the runtime and
false of the binary: firebase_core and firebase_messaging are unconditional dependencies of the
valence package, alongside flutter_local_notifications and app_badge_plus, so an offline app
with no account, no push and no reminders still ships them. FirebaseInitProvider runs on every
launch and logs that it found no default options, and FCM registers a service in the merged manifest.
Play's Data safety form and Apple's privacy manifest ask about SDKs that are present, not SDKs
that are reached, so if you are submitting a Valence app, declare them as present and unused: no
token is registered and nothing is collected without a configured push adapter. You cannot remove
them — dependency_overrides re-points a package, it does not drop one.
No code changed. Moving push into a separate valence_push package that an app adds when it declares
push.* is the real fix and is not in 0.4. The store-policy, remote-push and contracts text now say
all of this where an adopter will read it.
codegen refuses a built-in declared below its reserved since #
A built-in's since is the version the runtime reserved for that name, not a number your app
chooses — the delegation is only generated at or above it. Declaring one below made the name
app-owned silently: codegen emitted an abstract handler, ValenceBuiltins did not satisfy it, the
host stopped compiling with a message that looked like the package had forgotten to ship something,
and writing the handler by hand compiled and reimplemented a built-in.
codegen now refuses it and names the number to use. Four names carry a floor, because they were in
use as app-owned methods before the built-ins existed: notify.* and badge.* at 11, push.* at
12, and share.image at 14. Every other built-in still delegates at any since.
Only a declaration carrying the built-in's own signature is refused — that is what copying the template and renumbering it produces. A method of your own under one of those names, with its own params and return, keeps its abstract handler exactly as before, and so does a name your recorded store schema already shipped.
If codegen now fails for you, raise that method's since to the number the message gives. Your
schema's own version is unaffected. The permissions guide, which told you to assign your app's next
version to copied built-ins, is corrected, and the bridge guide has the floors in one table.
a sync scoped to nothing can no longer report success #
sync.now({ buckets }) naming only buckets the host does not have — a typo, or a
bucket a newer bundle renamed — attempted nothing and reported reason: "ok", and
persisted that over a stored unauthorized. A page's "sign in again" banner reads
sync.status(), so one scoped call could make a refused account look healthy.
A scoped run that matches no read pair, no writable bucket and no outbox bucket now
reports failed, logs the names it was given, and writes no observation, so the last
real outcome stands. A scope that does match any bucket is unchanged. Upgrade the
native host package; no schema or app change is needed.
a missing notification icon no longer takes the app down #
- A native notification service that refuses to start no longer throws out of
Valence.open. The host logs the native code and the reason and runs with notifications unavailable:notify.schedulereportsblocked,notify.pendingis empty,badge.setis false, and the rest of the app is unaffected. A host that cannot post a notification is still an app. - The usual cause is Android's release resource shrinker.
notifications.iconis named only as a string invalence.config.json, so nothing references the drawable and R8 deletes it — which no debug-build check can see.valence doctornow has anotification iconrow that fails when the drawable is missing fromandroid/app/src/main/resor whenres/raw/keep.xmldoes not name it. If you have notifications enabled, addres/raw/keep.xmlwithtools:keep="@drawable/<your icon>"and run a release build. - The notifications guide says this where the icon is introduced, as a requirement rather than a tip,
and now shows the three-line adapter for delegating a shipped custom
notify.*method to the built-in scheduler — there is no separate service class to import.
a replaced OS snapshot cannot cross an account or a bundle #
A replacement task snapshot handed to an already-running host is now checked against the
account fingerprint and bundle seq that startup verified, and dropped whole on a mismatch.
Before this, restoring a snapshot saved under one account after switching to another served
the first account's route and draft through state.restore(), and an older bundle's blob
skipped the seq check. Upgrade the native host package; no schema, config or app handler
change is needed.
native plugin registration checks #
Regenerated handlers reject missing plugin namespaces and exact native methods at startup in every build mode. Register the matching plugin instances, regenerate with matching tooling/runtime snapshots, test your real app handlers and rebuild the host. Doctor lists requirements as a warning; native setup and successful behavior still need testing.
development mode identifies skipped OTA operations #
Debug hosts now log the upstream origin and disabled OTA behavior at startup. Calls to ready, signed reload, update checks and applyUpdate log their development bypass rather than appearing silent. Restart without VALENCE_DEV_URL to validate signed offline starts and rollback. No schema, package version or host setup changes are required.
explicit LAN development trust #
valence devnow binds loopback by default. A LAN address or hostname requires--allow-lan; that mode binds all interfaces and names the cleartext full-bridge risk before starting. Add the flag to existing physical-device dev commands. Manual Flutter defines remain explicit trust grants; release/profile exclusion is unchanged. Refresh vendored tooling when upgrading.
capability and status fields #
Schema 15 adds nullable builtins, persisted sync reason and signed pending urgency. Regenerate and ship a store build; declaring builtins also requires current optional params on declared built-ins. Earlier hosts and schemas keep working. Account changes clear the new sync observation.
dev-mode and plugin hardening #
Valence.emitenforces the §4.2 256 KB envelope cap, so an oversized event — now possible because §4.10 lets a plugin emit one — is dropped with a log line instead of killing the WebView and spending a trial strike.- A test asserts every
VALENCE_DEV_URLread inlib/is guarded bykDebugModein the same expression, which is what makes the §3.1 dev path compile-time absent from release builds. tool/check-release-dev.mjsmatches app-bundle AOT paths (base/lib/<abi>/libapp.so) as well as APK ones.
account-switch hardening (§4.4) #
Valence.dataPutthrowsE_INTERNALfor the duration of an account transition, which now spans the sync-lease wait as well as the clear. Writes already in flight are drained beforeclearWritable, so one cannot commit after the delete and be pushed under the next account's token.ValenceStore.clearWritableno longer returns early on an empty bucket set: the outbox check, the outbox delete and the sync-observation reset are not bucket-specific and always run. Only thekv/bucketdeletes are conditional.auth.setTokenrecords the account id before writing the token on the non-switch paths too, matching the switch, so an interrupted adoption cannot leave a token with no recorded identity.
task restoration #
Task restoration now checks the native account before loading a restored route, clears drafts on account switch/sign-out and refuses late route captures from the previous account. Refresh and first-account adoption keep the live draft.
Schema 8 adds state.save({json}) and state.restore() for a task-local UI blob (65,536 JSON UTF-8 bytes). ValenceApp restores the local path/query/hash after OS process reclamation. Explicit task closure starts fresh; a different bundle seq clears the snapshot. Save promptly and keep durable records in SQLite. iOS is experimental and untested.
permissions (R3) #
- Added schema-9 permission checks, serialized foreground requests, app settings and resume changes. Hosts opt in with
permissions.kinds, native declarations, codegen and a store build. Android checks preserve uncertain denial; iOS remains experimental and untested.
local reminders #
Schema 11 adds built-in local reminders: notify.schedule/cancel/pending/channels.set, notify.permission, consuming notify.initial, notify.tapped/notify.action and best-effort badge.set/clear. Opt in with notifications.enabled, regenerate, install native receivers/icon/desugaring and ship a store build. Exact requests report downgrades honestly; one-shot epoch times need no device timezone lookup. Images are bounded PNG/JPEG bytes; every action opens the UI. iOS is experimental and untested. Android hosts now need core library desugaring even when the feature is disabled, because the native plugin ships with the runtime. Existing custom notification IDs must be coordinated; pre-schema-11 custom methods retain their shipped shapes and app-owned handlers.
remote push #
Remote push is opt-in in schema 12: push.token, passive/explicit push.permission, consuming push.initial, push.received, push.tapped and push.tokenChanged. Firebase runs only in configured hosts; exact data-only sync hints use the existing native sync without touching OTA state. Android notification images use FCM background display; foreground messages reach the page. Device validation is blocked: needs Firebase project. iOS/APNs is experimental and untested. Existing hosts must add the additive schema, regenerate, configure Firebase and ship a store build. Unicode line separators are escaped in event/reply scripts without changing JSON values.
image sharing #
Valence.shareImage backs schema-14 share.image with capped base64 input or a
re-verified active signed bundle image, filename and caption validation, and native
PNG/JPEG sharing through share_plus. Selection is not proof of delivery.
iOS remains experimental and untested. Add the method through codegen and a store
build; existing custom pre-14 declarations retain their own handlers.
Sync correctness: pull cursors advance only through returned rows, never push echoes or a later server-head max. Fresh pairs satisfy OTA activation only after all pages or static chunks complete. Progress resumes after an interruption. Pending publication retains the data lease; GC protects in-flight manifests and retries stale snapshots. Step 7 waits up to five seconds for ordinary sync. Outbox operations use a durable insertion ordinal; database version 2 migrates legacy queued ids, values and deletes without changing bucket cursors or user rows.
native HTTP and REST adapter #
Call your API with http.request (schema 4): the host enforces compiled http.origins origins, attaches the stored token, and never follows redirects. Existing hosts need codegen and a store build to add the capability or origins. A reference Node REST-to-sync adapter demonstrates durable pagination, tombstones and idempotent pushes. iOS remains experimental and untested.
account switching is safe #
Schema version 13. Valence.authSetToken takes account and discardPending, and Valence.authAccount()
is new. Recording a different opaque account id, or signing out with one recorded, clears every writable
bucket's rows, max_usn cursor and the whole outbox in one transaction under the sync lease, before the
new token is stored, and emits sync.changed for those buckets. It throws the new E_PENDING
(BridgeErrorCode.pending) and changes nothing while the outbox is not empty, unless discardPending is
set; it fails with E_INTERNAL rather than clearing underneath a sync that holds the lease, and it keeps
the lease until the new token is written, so a sync starting in between cannot pull the previous
account's rows back under the previous account's token. Only null is the sign-out — an empty token
clears the token and no data. A refresh of the recorded id, a first id with none recorded, and an app
that never passes one all clear nothing, so a host upgrade cannot wipe an existing user's data. An
account id the Keystore cannot return throws E_INTERNAL instead of reading as "none recorded", which
would have made the next sign-in an adoption over the previous account's rows. iOS remains experimental
and untested.
lifecycle, connectivity and update status #
Bridge version 6. ValenceApp maps Flutter's five lifecycle states onto four and emits app.lifecycle
only on a change (hidden and paused are both background, because Android delivers both for one
backgrounding); it emits app.online from the connectivity it already watched, reading the current
value at start-up rather than waiting for a change; and it emits sync.done with the whole
ValenceSyncResult after every completed run, after sync.changed for the same run.
Valence.appState() and Valence.bundleStatus() back the new app.state and bundle.status
built-ins and never start a request. Every stop in the §2.3 check now records a ValenceBundleReason,
so a page can tell a rollout gate from a release waiting for its data from a release no device will
take. Persist on background, not detached. iOS remains experimental and untested.
offline tooling #
- Add schema-3 data.getMany and sync.status, and optional SyncResult.pending. Regenerate an additive schema and guard the new methods on older hosts.
- Seed multiple declared read-only schemas using seedSchemas and versioned files; the runtime imports each declared pair.
- OTA bundle bridge requirements now default to the recorded store baseline. Guard newer methods; explicitly pin lower if older store builds remain supported. Built-in/store defaults still use the current schema.
- Compile ota.channel and generate opt-in BridgeHandlersDefaults for test doubles.
- Run mechanical doctor diagnostics and mapped unit tests without an interactive session. Unexecuted evidence stays WARN.
- Constrain path_provider_android to the pre-JNI range >=2.2.17 <2.3.0 while compatibility is validated (U-7, 2026-10-21).
First release of this package #
- Native extensions can implement
ValencePlugin, with namespaced schema fragments and matching npm types. Generated adapters keep strict decoding; the built-in open group uses the same registry without allowing its owner to be replaced. The example haptic handler is now a separate local plugin package.
First release. The Flutter host runtime that /valence init used to generate into every app now ships as
a package, so a fix reaches every adopter with flutter pub upgrade instead of being hand-applied.
Implements contracts.md:
- §2.3, §2.4 — the canonical manifest check order, the activation state machine with its two-strike
rollback, roll-forward, and garbage collection that keeps
current,previous,pending,trialand the built-in bundle. Step 7 pulls therequires.datapairs a bundle needs, under the §5.6 lease. - §3 — the loopback server: a per-install port in 10000..29999, a per-launch nonce in the entry page,
the three serving branches in their contractual order with the reserved
/_host/prefix matched first, path normalisation, and lazy content-addressed integrity re-checking. - §4.4 — secure storage and the bearer token:
secure.get/set/deleteover the Android Keystore and the iOS Keychain,auth.setToken/auth.hasTokenkeeping the token at the reservedvalence.auth.tokenwhere the page cannot read it back,Authorization: Beareron every writable bucket's pull and push, andauth.expiredplusValenceSyncReason.unauthorizedon a 401. NeedsminSdk 23on Android. - §4.2 — the strict decoders, the closed error-code set, the 256 KB UTF-8 message cap in both
directions, and event scripts built only through
jsonEncode. - §5 — the SQLite store with the pragmas through
rawQuery, a never-closed connection shared across isolates, the seed import counted withchanges(), per-(bucket, schema)storage, the outbox, pull paging, push with its echo skip, and the sync lease. - §3 back gesture, console capture and resume —
PopScopeasking the WebView first,setOnConsoleMessageplus the page callbacks, and port reclaiming on resume that keeps the nonce when the same port comes back.
Also here, and not in the generated hosts it replaces:
ValenceConfig.authToken, so an app with its own refresh loop in Dart can own the token instead; when it is unset, the host uses whatever the page stored throughauth.setToken.ValenceConfig.syncMode: staticChunks, the CDN-only pull from §5.3's static variant.ValenceConfig.databaseName, so a 0.3 app whose generated host chose its own file name keeps its data.Valence.publishHostFile, the only path from native bytes to the page.Valence.pendingWrites(), which counts queued deletes ausn == -1scan cannot see.
Corrections an independent review found before this first release, each with a regression test:
- A writable bucket is pulled as well as pushed, at schema 1. It can never appear in a manifest’s
requires.data, so a host that pulls only those pairs leaves user data push-only: a second device never sees a row, and a reinstall comes back empty. - A mid-session reload runs §2.4 step 4 only. Re-running the UI-start transitions made
bundle.applyUpdatespend a strike on the bundle it was promoting, and made a ready timeout re-serve the failing trial instead ofcurrent. - Garbage collection keeps the files of a download in flight. Step 6 writes CAS before step 8 writes the manifest, so a collection in that window could delete what had just been fetched — after which nothing re-fetched it and a healthy release failed its trial twice.
- A refused built-in bundle is remembered by its manifest bytes and the host’s bridge version, not by its seq, so the host upgrade that fixes a check-5 mismatch is not skipped by the record meant to save work. The seq gate also runs before the verify, so an ordinary launch does not check a signature.
- A corrupt file of the active bundle is re-fetched by a repair pass before step 1. Step 1 stops
before step 6 for a bundle that is already
current, so a rotted entry page was a permanent blank screen. - The seed is extracted once per host build, not on every launch in front of the first frame.
ValenceStoreenforces the reservedvalence.pref prefix itself, so an app that defines its own settings method cannot become a route to the sync lease.
284 tests. dart analyze --fatal-infos clean. flutter pub publish --dry-run has 0 warnings.
adaptive layout and accessibility #
ValenceApp requests edge-to-edge layout, publishes system-bar/cutout inset CSS variables on load and metrics changes, follows Android system text zoom and emits schema-7 app.appearance snapshots. Add optional AppInfo.fontScale: "num?" and regenerate; old schemas remain supported. Existing pages must pad content/fixed controls using the variables and avoid double-scaling Android text. Custom hosts can pass their FlutterView to Valence.attach for matching font-scale reporting. iOS root-font scaling remains experimental and untested.
Firebase dependencies now require iOS 15.0 or later, even with push disabled. Upgrade Runner/extension target settings; iOS remains experimental and untested.
Bridge success and error reply caps now include Unicode separator escaping; oversized errors retain only safe numeric correlation ids.