Skip to main content

valence 0.4.0-beta.1 copy "valence: ^0.4.0-beta.1" to clipboard
valence: ^0.4.0-beta.1 copied to clipboard

PlatformAndroid

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's waiting line for sync.acquireLease is 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. ValenceSyncStatus and acquireLease still read one predicate;
  • nothing reported as an age can be negative. A displaced row ahead of now logs dated <n>ms in the future and names the TTL it exceeded; ValenceSyncStatus.leaseAgeMs floors 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.request begun as one user could deliver its Set-Cookie after that user signed out, which refilled the cookie jar the sign-out had just emptied — in memory, and in the Keystore once sessionCookieDays was 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.cache overlay, 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.cache answers E_DENIED and says why.
  • codegen no longer throws on a payload field named after an Object member. An event declaring constructor or toString was 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 since to declare, and the docs now say so where data.cache is introduced: declare max(18, your next schema version), which is what codegen computes for you. The refusal that follows a changed built-in now tells you to restore the recorded since instead of offering a .v2 rename, 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 404 there makes the whole run report failed and 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.

  • Native http.cookieJar.sessionCookieDays opts 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.check and bundle.checked completion, including offers needing a newer store host. Regenerate and rebuild to opt in; pending-only bundle.updateReady is unchanged.
  • 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: ValenceHttp sends no Cookie, discards every Set-Cookie, and touches secure storage only to notice there is nothing to revoke. The origin is compiled from http.cookieJar by valence codegen, which refuses one that is not also in http.origins, a cleartext non-loopback one, and a mirrored CSRF header the host already controls.
  • ValenceCookies holds the jar for the runtime's lifetime, so one secure-storage read serves every request. It is host-only by Domain, matches Path per RFC 6265 §5.1.4, prefers Max-Age over Expires, caps at 16 cookies / 4096 bytes each / 8 KiB total, keeps a session cookie in memory only, and persists an expiring one at the reserved valence.http.cookies key, which secure.get cannot read. A malformed Set-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.open revokes 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. ValenceCookies validates its own origin — HTTPS unless loopback, exactly normalised, present in httpOrigins — and seals rather than replaying a credential in the clear for a hand-written config. csrfValue is path-matched like header. Secure is 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, owns refuses 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.hostControlled is now public, and the CSRF mirror is checked against it: a configured header the host already sets throws E_INTERNAL rather than silently overwriting the bearer token or the jar's own Cookie. 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-session minHost block takes the page down, so ValenceApp'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 on 127.0.0.1 behind 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 activateForUiStart twice — the second reading the first's own serving as 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.cache overlays with it. ValenceUpdater.countFailure clears the cache table on both strikes, not only the one that marks a bundle bad, because one strike already puts current back 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 #

  • ValenceApp handles an onWebResourceError of type webContentProcessTerminated: 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 clears serving so §2.4 step 2 does not spend the strike on the next UI start either, while trial stays 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_android 4.14.1 (newest, checked 2026-11-01) exposes no onRenderProcessGone, so Chromium kills the host process before any Dart code runs — and because no Dart code runs, serving survives 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.request answers E_TIMEOUT for its 20-second deadline and E_OFFLINE when the OS reports no network interface, keeping E_INTERNAL for a captive portal, a firewall or a server that is down — the cases it cannot honestly tell apart. ValenceHttp takes an optional online callback; with none, the behaviour is unchanged. Every E_TOO_LARGE names the observed size and the limit, the streamed one as a floor.
  • valenceStoreUrl matches the platform case-insensitively. The runtime passes defaultTargetPlatform.name, which Flutter spells iOS, so the iOS branch was unreachable on every iOS device and app.openStore answered E_UNSUPPORTED with a valid store.iosAppId configured.
  • 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.schedule reports blocked, notify.pending is empty, badge.set is 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.icon is named only as a string in valence.config.json, so nothing references the drawable and R8 deletes it — which no debug-build check can see. valence doctor now has a notification icon row that fails when the drawable is missing from android/app/src/main/res or when res/raw/keep.xml does not name it. If you have notifications enabled, add res/raw/keep.xml with tools: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 dev now 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.emit enforces 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_URL read in lib/ is guarded by kDebugMode in the same expression, which is what makes the §3.1 dev path compile-time absent from release builds.
  • tool/check-release-dev.mjs matches app-bundle AOT paths (base/lib/<abi>/libapp.so) as well as APK ones.

account-switch hardening (§4.4) #

  • Valence.dataPut throws E_INTERNAL for the duration of an account transition, which now spans the sync-lease wait as well as the clear. Writes already in flight are drained before clearWritable, so one cannot commit after the delete and be pushed under the next account's token.
  • ValenceStore.clearWritable no 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 the kv/bucket deletes are conditional.
  • auth.setToken records 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, trial and the built-in bundle. Step 7 pulls the requires.data pairs 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/delete over the Android Keystore and the iOS Keychain, auth.setToken / auth.hasToken keeping the token at the reserved valence.auth.token where the page cannot read it back, Authorization: Bearer on every writable bucket's pull and push, and auth.expired plus ValenceSyncReason.unauthorized on a 401. Needs minSdk 23 on 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 with changes(), per-(bucket, schema) storage, the outbox, pull paging, push with its echo skip, and the sync lease.
  • §3 back gesture, console capture and resume — PopScope asking the WebView first, setOnConsoleMessage plus 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 through auth.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 a usn == -1 scan 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.applyUpdate spend a strike on the bundle it was promoting, and made a ready timeout re-serve the failing trial instead of current.
  • 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.
  • ValenceStore enforces the reserved valence. 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.