Capability revisions and durable status
Schema 15 adds nullable returned fields. Regenerate the bridge and ship a store build; an OTA cannot add native support. Existing store baselines stay unchanged. Old hosts omit these fields, so use nullish fallbacks. Android is the validation target; iOS remains experimental and untested.
Gate grown parameters
Section titled “Gate grown parameters”app.info().bridge is your app’s schema number. builtins is Valence’s capability
revision, currently 20, independent of how many custom methods your app added.
const info = await call('app.info');if (has('data.list') && (info.builtins ?? 0) >= 5) { await call('data.list', { bucket: 'places', after: lastKey, limit: 100 });}Declaring builtins: "int?" on the app.info return type opts into current
parameter shapes for declared built-ins. Codegen rejects a reporting schema that
omits data.list.after or auth.setToken.account/discardPending. Update those
optional params too, or omit builtins and keep the earlier sibling-method gates.
Methods may still be omitted or disabled: use has() and the capability’s
permission/opt-in rules. has('data.count') remains the compatible cursor gate
for earlier hosts that support paging but have no builtins field.
Reconstruct the last sync outcome
Section titled “Reconstruct the last sync outcome”reason is a new optional field, so run npx create-valence update before declaring it. A generator
older than this page rejects the whole type with “its fields are not” and no mention of tooling; it now
names the field it does not know and the command that fixes it
(details).
sync.status().reason survives redraws and restarts because it is stored in native
SQLite, atomically with the other sync observations before releasing the lease.
It is null before an attempt, including a migrated database. Busy/skipped runs,
no-server runs and thrown failures retain the previous observation. A completed
scoped run replaces it too; only a successful unscoped run advances lastSyncedAt.
Account switch/sign-out clears it with the account’s rows and other observations.
unauthorized can now reconstruct a sign-in warning after navigation. The string
set is open: unknown values are not success. This is the last attempted scope,
not an acknowledgement for every bucket. Keep an app-owned receipt if an error
must stay visible until an explicit authenticated check succeeds. An anonymous
401 is stored as failed, without emitting auth.expired; the stored reason
matches the returned result. See Sync outcomes.
Older hosts still need the documented prefs fallback.
Read the pending update’s urgency
Section titled “Read the pending update’s urgency”bundle.status().urgent is true or false only after re-verifying the pending
bundle’s signed local manifest. No pending bundle, failed verification or a
concurrent pending change produces null. It never describes the pointer’s offer,
starts a download, or activates a bundle. Both false and true updates remain
eligible for the existing explicit applyUpdate flow and emit updateReady.
The Dart API keeps synchronous bundleStatus() for existing callers; generated
schemas declaring urgent use the additive async bundleStatusWithUrgency().
Urgency can change wording or prominence, and never bypasses trial/ready/rollback.
Schema 16: read pending reminder IDs at the cap
Section titled “Schema 16: read pending reminder IDs at the cap”Schema 16 adds one method and changes nothing that shipped: notify.pendingIds()
returns the native pending queue as a bare int[]. A full queue of 64 requests at
their maximum title, body and payload sizes is about 540 KB, over the bridge’s
256 KB reply cap, so notify.pending() answers E_TOO_LARGE on exactly the apps
that keep the most reminders queued — and that was the only documented way to
discover pending IDs for a cancel-by-difference refill. notify.pending() keeps
every field it has. Gate it with has('notify.pendingIds'); see
Local notifications.
Revision 20: who holds the sync lease
Section titled “Revision 20: who holds the sync lease”Two more nullable returned fields, on SyncStatus: leaseKind and leaseAgeMs.
reason says a run was refused; these say by what, and for how long — leaseAgeMs
counting from when the holder took the lease, so it only increases while one run
holds it. leaseKind
is foreground, background, push, or unknown for a held lease written by an
older host — and both fields are null whenever a run starting now would not be
refused, including a lease this host is about to take over. Gate on
(info.builtins ?? 0) >= 20. They are for reporting a stuck-looking sync
accurately, not for deciding a holder has leaked: full rules and an example in
Sync outcomes.
Source of truth: contracts, “Schema 15 returned-field additions (R17)”,
“Schema 16: notify.pendingIds (R28)” and
“Revision 20 returned-field additions (S9)”.
Lease acquisition samples its clock after the lease query returns inside the transaction. A queued database read cannot mistake a sibling’s newer renewal for clock rollback, and waiting for the database does not consume a new lease’s TTL. The two-minute TTL, genuine future-timestamp recovery and foreign-process recovery retain their existing rules (K F-83). No schema change or app code adoption is needed; rebuild the native host.