koolbase_flutter

Offline correctness fixes.

• An offline add keeps one id. The id the app is given is now the id the record is created under when it syncs. Before, the server created the record under a different id, so an offline edit to a record added offline was sent to an id that did not exist and refused. (The same fix the JS SDK made earlier.)
• A refused offline add no longer lingers. When the server refuses an add made offline, the record is removed from the device's saved record and saved lists; the conflict keeps the user's data.
• Writes held behind a conflict stay held. Later queued changes to a record with an undecided conflict now wait across sync passes and restarts, instead of each becoming its own conflict on the next pass.
• Tested: the queued add's id, an add-then-edit chain replayed onto one id, the refused add leaving the saved copies, and a held write on a later pass.

• Realtime for signed-out visitors. With nobody signed in, live lists and live record views on a collection anyone can read (read rule public) now update live: the SDK connects with the project's public key. Any other collection behaves as a normal list or view until a user signs in. Needs the Koolbase API from 2026-10-04 or later. Same contract as @koolbase/* 12.13.0.
• Follows sign-in and sign-out. Signing in, signing out or switching user replaces the realtime connection with one for the new session and resubscribes everything; a token refresh for the same user changes nothing. KoolbaseRealtimeClient.sessionChanged() does this; Koolbase.initialize wires it to authStateChanges.
• Never public-only by mistake. Signed in without a usable token right now, or a token that fails to refresh: the SDK tries again later, as before, rather than drop to public-only.
• Tested. The public-key connection and its messages, events reaching listeners, no fallback while signed in, sign-in and sign-out replacing the connection, a refresh keeping it, nothing opened with nothing listening, and a session change while the token is on its way.

• Live record views: KoolbaseRecordView(..., live: true) (also KoolbaseRecordController(live: true)). When Koolbase realtime reports a change to THIS record, it is read again silently -- no refreshing state -- and a burst of changes within 250 ms is one read. When it is deleted, the view shows not-found at once, and a read still in flight is dropped. Changes to other records in the collection are ignored: no extra reads. Same contract as @koolbase/* 12.12.0.
• One connection. Live records and live lists share the app's single realtime connection (12.15.1).
• Needs a signed-in user, as realtime does; until there is one -- or before Koolbase is initialized -- a live record view behaves as a normal one. With no id there is nothing to follow and nothing subscribes. Without the option nothing changes.
• Tested through a realtime seam (liveEvents): a silent re-read on a change, other records ignored, one read for a burst, a delete at once and without a read, a delete dropping a pending re-read, no subscription unless live or without an id, and dispose unsubscribing and cancelling.

• Realtime subscriptions are counted exactly. Two listeners on one collection -- a live list and a live grid on the same screen -- were counted twice but cancelled once, so the collection was never unsubscribed and its events kept arriving after both had gone. A collection is now subscribed while its stream has a listener and unsubscribed when the last one leaves, however many share it.
• An unused connection closes. When the last listener leaves, the connection closes after a moment (idleGrace, 1 s). A listener back within it -- navigating back to a screen -- keeps the same connection; one after it opens a fresh one. Nothing reconnects without a subscription. Same contract as @koolbase/* 12.11.1.
• Sturdier. A token that throws no longer leaves the client stuck connecting; if everyone left before the token arrived, nothing is opened.
• Tested through a connection seam (connector), without a server: one connection for many listeners, unsubscribing only when the last listener leaves, the close after the moment, reuse within it, a fresh connection after it, nothing opened for nobody, and recovery from a failed token.

• Live lists: KoolbaseCollectionList(..., live: true) and KoolbaseCollectionGrid(..., live: true)
  (also KoolbaseCollectionController(live: true)). When Koolbase realtime reports a record
  created, updated or deleted in the collection, the list re-reads its first page from the network,
  silently -- no refreshing state -- and a burst of changes within 250 ms is one read. The list's
  own query is what re-runs, so filters, order and read rules stay exactly right. A failed re-read
  keeps what is shown. Same contract as @koolbase/* 12.11.0.
• Needs a signed-in user, as realtime does. Until there is one -- or before Koolbase is
  initialized -- a live list behaves as a normal list. Without the option nothing changes.

• Live lists refresh after doc(id).update and doc(id).delete. Every open query on the
  record's collection re-runs in the background, as it already did after insert, upsert,
  batch and deleteWhere; before, an update or delete through a document reference left every
  list showing that collection stale until it was reloaded. A delete of a record never read on
  this device refreshes every open query rather than guessing its collection
  (refreshAllCollectionStreams).
• A refused conditional write refreshes too. When update or delete with
  expectedRevision is refused because the record changed (KoolbaseRevisionMismatchException),
  the collection's open queries re-run, so the list already shows the newer data.
• Release notes. Version headings in this changelog are now ##, which the release workflow
  reads; with # every GitHub release since the workflow began had empty notes.

Merge pull request #9 from koolbase/release/12.13.0

fix: KoolbaseCollectionGrid inside a scrolling page

Merge pull request #8 from koolbase/release/12.12.0

feat: KoolbaseTestData, populated widget tests for lists and record views (12.12.0)

Merge pull request #7 from koolbase/release/12.11.0

feat: KoolbaseCollectionList(scrollsWithPage) for a list inside a scrolling page (12.11.0)

Merge pull request #6 from koolbase/release/12.10.0

feat: KoolbaseRecordView, one record by id as a scope (12.10.0)

Merge pull request #4 from koolbase/release/12.9.0

feat: analytics is opt-in, network errors carry a userMessage (12.9.0)

• Two-step sign-in (MFA). Every sign-in method now throws MfaRequiredException carrying a challengeToken when the person's account has an authenticator on — including phone, Google and Apple, whose error parsers all map it (a source test now enforces this for any parser added later). verifyMfa(email: …, code: …) and verifyRecoveryCode(challengeToken: …, code: …) finish sign-in and store the session.

  For managing MFA: enrollMfa(), confirmMfaEnrollment(code), mfaStatus(), stepUpMfa(…), disableMfa(), and regenerateRecoveryCodes(). Six new exceptions — MfaRequiredException, RecentAuthRequiredException, RecentMfaRequiredException, MfaAlreadyEnabledException, MfaEnrollmentNotFoundException and MfaNotEnabledException — each registered in the error-code fidelity suite.

• Sign in with an emailed code. requestEmailCode(email) sends a six-digit code; signInWithEmailCode(email: ..., code: ...) signs in and stores the session exactly as login does. No password needed.

  An unknown address becomes an account only while the project accepts sign-ups, checked at the moment of sign-in. Each code works once and allows three attempts. requestEmailCode resolves the same way whether or not the address has an account, so it cannot be used to check who is registered.

  A project can switch this off; requests then throw EmailCodeDisabledException. The OTP exceptions phone sign-in already uses — OtpInvalidException, OtpExpiredException, OtpMaxAttemptsException — now come from the shared mapping, so every path that returns them throws the class an app catches.

• Reference errors are catchable. KoolbaseReferenceInvalidException, KoolbaseReferenceInUseException, KoolbaseDanglingReferencesException (carrying the offending records) and KoolbaseCollectionReferencedException, for collections with declared references.

12.6.0: UploadResult exposes path and publicUrl, so a persisted uploa…

…d is never a signed URL that expires

12.5.0: session management, audit log, and resend verification withou…

…t a session

• Fourteen exceptions reported codes the API has never emitted. EmailAlreadyInUseException said email_taken for a server that says email_in_use; UserDisabledException said user_disabled for account_disabled; the Apple and Google exceptions each reported a provider-split code where the server sends one unified code. code is a public field, and anyone reading it instead of catching by type was comparing against a string that would never arrive. Catching by type has always worked and is unaffected.

• invalid_refresh_token was unmapped in the database path — the code the server actually sends when a session is over. It fell through to the generic fallback, so koolbaseDataErrorNotifying never fired for it and the session was not cleared. An app could keep a token the server refuses, which is the failure that notifier exists to prevent. It now produces KoolbaseSessionExpiredException, which four doc comments told applications to catch and nothing had ever thrown.

• A function that timed out was indistinguishable from one that threw. A 504 fell into the generic 5xx branch and arrived as FunctionExecutionException. Those need different answers — a timeout means retry or raise the limit; an exception means fix the code. Now FunctionTimeoutException, and 429 gets FunctionRateLimitException.

• Forty-four error codes the API emits were not mapped, arriving as bare exceptions so an app's on clause silently never ran. Thirteen in auth, including token_expired, token_used, account_exists, oauth_only_account and insufficient_scope; the rest across database, storage and functions, including revision_mismatch's siblings, plan_limit_reached (shared across all three families, carrying resource, limit and plan), ambiguous_match and upload_expired.

• KoolbaseNotFoundException and KoolbaseValidationException report the code they were built from, not their category. Each stood for several codes while reporting one, so a collection_not_found response produced an exception saying not_found.

• Why these were missing: The API wrote error codes through four different helpers, so no single search found them all. It now declares every code as a constant in one file, with a test that fails the build on a literal — which made the comparison against this SDK exact for the first time. That is how these were found.

Both halves are now guarded here: one test asserts every code maps to its own exception, another that every exception reports a code the server sends. The auth error mapping had never had a test before this release.

12.3.0: auth.changePassword for the signed-in user

Until now an app on Koolbase could not offer a change-password screen. Verifies the current password, signs out every other session, keeps this device in. Two new typed exceptions so a wrong current password and a rejected new password are distinguishable without string matching.

• Pagination. KoolbaseCollectionList and KoolbaseCollectionGrid show a "Load more" past the last loaded record while the collection has more -- exact, from the query's total, not a guess from a short page. KoolbaseCollectionController gains loadMore(), hasMore and loadingMore. A list that showed twenty and stopped was quietly claiming to be the whole collection.
• loadMore does not resubscribe: the realtime subscription stays on the first page, so a live insert updates that page in place and the pages loaded after it stay put. refresh() resets to one page.

• Koolbase.db.aggregate(...): count, sum, avg, min, max over the whole authorized set, grouped by a field or a calendar bucket. Every result carries its accounting -- how many records contributed and how many were skipped as missing or non-numeric -- so a total is never a bare number. A calendar bucket requires a timezone; the KoolbaseGroupBy.month(...) constructors make it impossible to omit. Online-only. Read rules apply inside the query.

12.0.0: Flutter Web

initialize no longer refuses the browser. Code push is skipped (no
binary, no bundle cache — path_provider has no web implementation)
and codePush throws with isCodePushAvailable false; offline sync is
skipped (drift on web needs wasm shipped beside the app). Auth,
database, storage, realtime and functions run. Proven on the example
app in Chrome against api.koolbase.com from a trusted origin.

• README documents KoolbaseCollectionList.visible; install snippet at ^11.6.1.

11.6.0: KoolbaseCollectionList.visible

Transform the loaded records before both the empty decision and the
rows. Runs on every build over what is already loaded; it does not
query. The Designer's search-on-list is built on it.

• Widget tests can now build Koolbase screens. Koolbase.initializeForTesting() sets up enough SDK for widgets to render — db and auth exist, every HTTP request answers with an empty success, auth storage is in memory — and none of the platform channels a widget test cannot answer. resetForTesting() pairs with it. InMemoryAuthStorage is public for your own tests.
• The httpClient passed to the database client now reaches every query and document reference. It was accepted and never used: queries called the package-level http.post, so a test client was cosmetic and the database could not be exercised without a network.
• An empty bound list inside a scrolling column no longer throws. The empty slot pinned its minimum height to the parent's maximum, which in an unbounded parent is infinite. Found by a generated widget test.

• Device outcomes are now attributable. Every patch event the SDK sent omitted patch_id, and the server only increments a patch's counters when that field is present — so every download and activation ever reported landed in the events table and moved no number. The staged patch id is now persisted alongside the staged patch number and promoted on activation, so the id survives the process boundary between downloading a patch and applying it.
• Android now reports patch_activated. The reconcile branch that promotes a staged patch on Android logged and returned without sending anything, so the platform carrying almost all real traffic had never recorded a single activation.
• Failures are no longer silent. A download that returns a non-200, a checksum mismatch, an engine that declines to apply a staged patch, and any exception thrown in the background check phase each now post patch_failed with a reason. Previously a device that could not install a patch was indistinguishable from one that never tried.
• app_version is populated on events rather than sent as an empty string.

11.4.1

A patch, not a minor: refusing on a platform that was never supported
adds no capability, and the version should say 'safe to take' rather
than 'something new arrived'.

11.4.0: runtime storage public URLs via bootstrap-learned project ide…

…ntity

publicUrlFor(bucket:, path:, transform:) needs no projectId — identity
arrives with the bootstrap payload the SDK already fetches, caches and
refreshes. Typed KoolbaseStorageProjectIdentityException while identity
is unavailable (distinct from null = private bucket); the throw nudges a
refresh so the session heals without restart. Update gate compares
project_id explicitly since it lives outside the payload hash. README,
CHANGELOG updated.

KoolbaseError: one canonical error type across the whole SDK

Catch anything, call KoolbaseError.from(e), branch on code. The 44 typed
exceptions are unchanged; this sits above them so an app can branch on what a
failure MEANS without knowing the SDK's internal taxonomy.

Found by measuring: across 14,732 lines, four places in the entire SDK catch a
transport failure. A database read that loses connection has been throwing a
raw SocketException straight through to the caller — on a phone with patchy
signal, the most common failure there is, and the one with no typed home.

Normalization is total: an unmapped server code, a bare string, an integer all
become a KoolbaseError rather than escaping. This runs in error paths, where a
second failure has nowhere to go.

Eleven codes. The bar for adding one is that an application could reasonably do
something DIFFERENT because of it — rateLimited because waiting is not
retrying, contactNotVerified because it routes to "resend verification" not
"check your password". retryable is derived from code, never stored, so the two
cannot disagree. details carries structured context through rather than
flattening it, including the server's current record on a revision mismatch.

message is developer diagnostic data and must never reach an end user. Written
into the doc comment, not just the changelog.

Also fixes the README's first auth example, which called a method that does not
exist (Koolbase.auth.register). signUp appeared nowhere in 1382 lines, so the
front page had no correct path to creating a user — including no mention of
SignUpResult.verificationRequired, where the account exists but no session was
issued.

Additive only. Nothing throws differently, no signature moved.

• Analytics events now carry the signed-in user automatically. identify() existed, but nothing errored when an app never called it — so every event landed anonymous, and retention, funnels and any per-user analysis were quietly worthless. Found by looking at a real project: 53 events, 8 registered users, zero events carrying a user id. The SDK already knows who is signed in; it should say so.
• identify() still wins where an app has its own identity system, and the existing reset() releases that override — without it, events keep carrying the previous user after they sign out.

• Koolbase.fiscal — authority-grade sales recording. submit() records a transaction and drives fiscalization; status() follows it and returns the certification the tax authority granted (in Ghana: the GRA signature, receipt number and verification QR a compliant receipt must carry). Live for Ghana's GRA E-VAT; the reference adapter runs the same machine — gapless numbering, sealed immutable documents, full evidence — anywhere an authority integration doesn't exist yet.
• The clientRef you pass is idempotent: resubmitting the same reference always returns the same intent, never a second fiscal number. A timed-out submit may still have fiscalized, so retrying or polling both converge on the truth — the exception message says so rather than leaving you guessing.
• Fiscal deliberately does NOT use the offline write queue. A register needs a real answer or an explicit "not yet"; silently queueing a fiscalization would let a cashier believe a receipt is legal when the authority has never seen it. Offline-capable point of sale should record the commercial sale locally and submit fiscally on reconnect — the idempotent clientRef makes that replay a single call.
• FiscalIntentResult exposes status, numbers, blockedReason, certification, isFiscalized and isPending. A blocked result means nothing was consumed — no fiscal number was spent — so fixing the cause and resubmitting the same reference resumes that exact transaction. A fiscalized result with a null certification is valid for document kinds the authority acknowledges without certifying (purchase records); it is never an error.

fix: offline writes refuse signed-out — never enqueue under a null owner

A ticket parked on-device while the SDK session was dead was enqueued
with userId null. Every per-user surface then did its job correctly —
pendingWrites() throws signed-out, reads and replay filter by owner — so
the null-owner row matched nothing, forever: physically present,
invisible, unreplayable. The write neither failed nor succeeded; it
vanished into a bucket nobody owns.

All three offline enqueue sites (insert fallback, queued update, queued
delete) now throw KoolbaseUnauthenticatedException signed-out. Signed-in
behavior byte-for-byte unchanged. Mutation-pinned: removing the insert
guard fails 'writes to NO bucket'. Mirrors the RN SDK's Aug 4 fix of the
same bug family. v11.1.1

feat: get(fresh: true) — cache-skipping network read

SWR cannot express read-after-write: a cached answer is the state before
your write, and awaiting the background-refresh stream proved racy
on-device (a local projection tracked the server exactly one sale
behind). get(fresh: true) skips the cache and returns the network's
answer; the read still updates the cache, so SWR callers benefit.
Plain get() unchanged. Fake queries in tests updated to the new
signature. v11.1.0

feat(auth)!: SignUpResult + ContactNotVerifiedException (11.0.0)

BREAKING: signUp returns SignUpResult, not KoolbaseUser.

The server can now withhold a session at registration when a project requires
a verified contact channel. The old return type could not express 'account
created, not signed in' — the session-less 201 reached AuthSession.fromJson
and threw 'type Null is not a subtype of type String' on the absent
access_token. Observed on device before this fix.

SignUpResult carries the user in both cases and a verificationRequired flag,
so consumers must branch. Deliberately not a nullable user or nullable
session on the public surface: that would push the same null-check onto every
caller and reproduce the crash one layer up.

The session is persisted only when one was issued. Calling _setSession with
null would leave the SDK half-authenticated — reporting a signed-in user with
no token.

signUp no longer routes through _parseSession. That parser assumes tokens
exist, which is correct for login and refresh and wrong for registration
under this policy; loosening it would have weakened login's contract for no
reason.

ContactNotVerifiedException maps the server's contact_not_verified code on
login. Credentials were correct and the policy refused, so it is distinct
from InvalidCredentialsException — apps route to resend-verification rather
than telling the user to re-check a password that was right.

Added only to _checkError, not to the Apple/Google parsers: OAuth satisfies
the requirement by definition (a provider attestation IS a verified contact),
so the server never emits this code on those paths.

Enforcement is off for every project that existed before the server-side
release, so verificationRequired is false and behaviour is unchanged unless a
customer opts in.

feat: KoolbaseCollectionGrid (10.5.0)

The same collection laid out as a grid. Deliberately thin: it shares
KoolbaseCollectionController with KoolbaseCollectionList, so
stale-while-revalidate, pull-to-refresh and the loading/empty/error
slots behave identically — the two differ only in layout, and sharing
the controller is what keeps them from drifting on the hard parts.

Fixed crossAxisCount rather than responsive reflow: a caller who needs
reflow can vary it from a LayoutBuilder, and building it in would have
meant guessing at tile sizing for everyone else.

Tests are narrow on purpose — the controller's properties are already
covered by the list's tests, so re-testing them here would test the
same code twice. The query fake moves to test/support so two copies
can't drift.

README's 'for grids, drive the controller directly' is no longer true
and now documents the widget instead.

10.4.0: streams fetch on listen, and writes refresh them

Two gaps that both surfaced as "the UI just does not update" — nothing
errored, nothing logged, the data was simply absent. Both were found by
building an app against the SDK rather than by reading it.

.stream was a bare relay off a broadcast controller: get() performed the
fetch and pushed refreshes into it, so a stream-only listener waited
forever on a collection nothing else had read. It now fetches on first
listen, cache-first exactly as get() is.

Every write invalidated the collection cache and stopped, which only
affects the NEXT query. A listener already watching sat unchanged until
something happened to re-fetch — a message sent into a chat thread did
not appear in that thread. insert, upsert, deleteWhere, batch, and
conflict resolution now refresh open queries on the collection.

Each query re-runs ITSELF, so a stream only receives records matching its
own filters. The refresh is a registered closure per stream rather than
one rebuilt from the stream key: a key carries collection, filters, and
user but not ordering, limit, or populated fields, so a reconstructed
query would push the wrong records into a stream that never asked.

Mutation-verified: dropping the collection filter refreshes every query
in the process, failing three tests.

README gains a Live queries section — .stream was undocumented — and its
where() example is corrected to the real named-argument signature.

KoolbaseAuthGate, KoolbaseAuthScope, KoolbaseCollectionList, and
KoolbaseCollectionController ship as the first behavioral widgets: the
SDK now encodes auth branching and the stale-while-revalidate list
contract as composable components rather than patterns every app
hand-writes. Query refresh streams are now keyed by query identity
rather than collection name, matching their documented contract — see
the changelog behavior note. README gains a Widgets section and catches
up two versions of version-string drift (was still ^10.1.2).

database: insert-conflicts are real, and resolvable (10.2.0)

The Flutter twin of RN 94d8a21, closing the cross-SDK batch. Unique
constraints made insert-conflicts a genuine third kind: a queued insert
refused as a duplicate is held like any terminal refusal — but the client
coerced its operation to update (ConflictOperation admitted only two members),
and resolving one issued a PATCH against a record id that exists nowhere.
Storage never lied; only the mapper did.

ConflictOperation gains insert. Resolving a rejected insert IS the insert,
retried: resolveWithMerge carries amended data (the fix-the-colliding-title
path), unconditional — no record, no revision to be conditional against — with
the conflict's id as the idempotency key, so a resolution whose response is
lost returns the original on retry rather than duplicating. Wire-proven on the
exact route. resolveWithServer means the colliding row stands: clears with
zero requests, asserted by request count.

Seeded through the production path (enqueue → moveToRejected). Mutation-
verified: deleting the insert branch resurfaces the pre-fix wrong-verb PATCH,
caught by name by a scripted client that refuses unknown routes loudly.

README documents the insert-conflict resolution semantics in the same change.

database: a refused resolution teaches the stored conflict (10.1.2)

The Flutter twin of RN fb4480d, live in a published SDK until now. Resolution
was conditional on the revision the ORIGINAL refusal reported; when the record
moved again mid-decision, the 409 — carrying current_revision and the record —
was correctly refused and entirely discarded by _resolveWrite. Every retry
replayed the stale condition; abandon was the only exit. Device-proven on RN
(three identical refusals against an unchanged server).

Flutter's factory already parsed the 409 fully into
KoolbaseRevisionMismatchException — the information died one method later. The
fix is one catch: refreshConflict absorbs currentRevision and currentRecord
into the Drift row (honoring serverState's own documented contract — 'as
returned with the refusal, so resolving does not need a fetch' — which the
CREATING refusal honored and the resolution refusal violated), then rethrows
with review-and-retry.

Proven by the revision sequence [8, 9]: the second attempt is conditional
against the LEARNED revision and succeeds without the server moving again.
Seeded through the production path (enqueue → moveToConflict). Mutation-
verified: removing the refreshConflict call fails the storage assertion.

The resolution HTTP path gained an injectable client (httpClient param) —
an unmockable resolution path is why no test ever caught this.

Breaking: Koolbase.messaging.send() removed. Sending push notifications is server-initiated only — it requires a secret kb_live_ key and must run on your backend or in a Koolbase Function, never in the app. The publishable key the SDK holds ships inside your app binary; allowing it to send would let anyone who extracts it push to your users. The API already rejects publishable-key sends with 401. Device registration (Koolbase.messaging.registerToken) is unchanged. See docs: /sdk/messaging.

Fixed: in-app functions.deploy() now uses the auto-refreshing session token. It previously read a manually-set static token that expired after 15 minutes while invoke() (which already auto-refreshed) kept working — so a long-lived app could see deploys fail while invocations succeeded. deploy() now shares invoke()'s token path. The removed setAuthToken() method is no longer needed; the SDK manages the session token itself.

Fix: package failed to compile on stock Flutter (all platforms). 9.4.0 unconditionally imported dart:_internal (VM code-push bindings that resolve only against the Koolbase-patched engine). The stock Dart frontend rejects platform-private imports at kernel compile, so every build failed with "Can't access platform private library" — analyzer-clean, caught only at build time. The bindings are now a stock-safe stub: on a stock engine, code push reports "engine not present" through existing failure paths (koolbaseBuildId() returns '', applyKoolbasePatch returns sentinel -990). No API changes; upgrading from 9.4.0 requires no code changes.

• Code Push (VM-level, iOS): flash-free boot apply. Koolbase.initialize now completes the iOS boot-time patch apply (local disk only, ~5ms measured on device) before returning, so the app's first frame already runs the patched code — the brief v1→v2 flash on cold launch is gone, with zero configuration. The network check/download remains fully asynchronous and can never block startup.
• Code Push (VM-level): device outcome events. The client reports patch_downloaded (on successful stage), patch_activated (on the boot that promotes a new patch, with patch_number), and patch_failed (on rejection, with the rejection code and whether the artifact was newly staged or the durable copy) to /v1/code-push/patch-events. Dashboards and rollout decisions can now count real device activations instead of inferring installs from patch-check serves. Fire-and-forget: event reporting never delays boot and failures are silent.
• Code Push (VM-level, iOS): correct patch bookkeeping after rejections. The boot apply now records what actually happened (new patch applied / durable re-applied / clean base boot) and reconciliation consumes that record. Previously, a rejected download that fell back to the existing patch could mark the rejected patch as current — the device then reported a patch it wasn't running, suppressing future update offers. A clean base boot (e.g. after an app-store update invalidates a persisted patch) now also resets the reported patch to 0.
• Code Push (VM-level, iOS): rejected patches are quarantined, not retried. A persisted patch that fails verification (for example, stale after an app update) is moved aside on first rejection instead of being re-read and re-rejected on every subsequent launch. Quarantined artifacts are removed once a healthy boot completes.

• Code Push (VM-level): the client now reports flutter_version on patch-check so the resolver can refuse a patch built on a different Flutter engine version.
  • Reads the CLI-stamped assets/koolbase_flutter_version asset (written by koolbase build / koolbase release) and sends it alongside build_id / release_version.
  • Pairs with the server-side resolver guard that constrains matching on flutter_version, closing two cross-engine mis-serve cases (colliding build_id across engine versions; release_version matching on app version alone).
  • Fully backward-compatible: an app built without the asset sends no flutter_version and the server falls back to legacy matching — no change for apps already in the field.

• Widen package_info_plus to >=8.0.0 <10.0.0 and flutter_secure_storage to >=9.0.0 <11.0.0. The SDK only uses the stable surface of both (PackageInfo version/buildNumber; SecureStorage read/write/delete with default AndroidOptions and standard KeychainAccessibility), so the previous latest-major pins needlessly blocked — and for secure_storage risked force-migrating — host apps on the prior major.

• Code Push (bundle): recall/rollback now actually reverts a recalled bundle on device.
  • The runtime resolver persists a pending-revert marker when the server issues a rollback and consumes it at the start of the next cold launch, before re-applying any stored bundle. Previously the rollback was logged but never persisted, so a recalled bundle kept re-applying on every launch.
  • Pairs with the server-side resolver fix returning rollback/revert_to:0 when a device runs a bundle that has been recalled with no published replacement.
  • Affects iOS and Android bundle recall.

• Code Push (VM-level): KoolbaseVmPatchClient — over-the-air Dart code updates for Android.
  • Self-contained: no MainActivity or platform-channel wiring required.
  • Checks in with the Koolbase resolver, downloads and stages patches; the Koolbase engine applies them on next launch with signature + build_id verification and automatic crash-revert.
  • Per-ABI build_id resolution for multi-ABI app bundles (arm64-v8a / armeabi-v7a).
  • Reports the running build's build_id and current patch number on check-in.

Breaking changes

• None. mode and minSimilarity are both optional; existing searchSemantic callers continue to work unchanged. Major bump reflects the conceptual expansion of the search contract (three retrieval modes instead of one), not API-breaking removals.

Object versioning support — full read + write surface against versioned buckets. None of this changes existing behavior on non-versioned buckets.

New

• KoolbaseObjectVersion model — one entry in a path's version timeline. Carries versionId, size, metadata, isDeleteMarker, isCurrent, createdAt and the rest of the version-row shape.
• KoolbaseStorageClient.listVersions({bucket, path}) — returns the full timeline newest-first, current + history mixed.
• KoolbaseStorageClient.getVersion({bucket, path, versionId}) — metadata for one specific version.
• KoolbaseStorageClient.restoreVersion({bucket, path, versionId}) — brings a history version back to current; the previously-current row is snapshotted to history first, so the restore is itself a versioned event.
• KoolbaseStorageClient.purgeVersion({bucket, path, versionId}) — hard removes a single history version (row + R2 bytes).

Extended

• KoolbaseStorageClient.getDownloadUrl(...) accepts an optional versionId — when present, the returned URL points to that specific version's bytes from .versions/.
• KoolbaseStorageClient.delete(...) accepts an optional forcePurge — true wipes the entire timeline for the path (all history rows, all .versions/ R2 keys, canonical, and the current row).

• feat(storage): edge image transforms (Gap #8).
  • New KoolbaseImageTransform value class — width, height, format, quality, fit, dpr, gravity. Pair with the new KoolbaseImageFormat, KoolbaseImageFit, and KoolbaseImageGravity enums for type-safe option construction. Out-of-range numeric values clamp silently to Cloudflare's valid ranges (width/height 1–2000, quality 1–100, dpr 1–3).
  • KoolbaseStorageClient.publicUrl({transform}) and KoolbaseObject.publicUrl(bucket, {transform}) accept an optional transform; the resulting URL hits Cloudflare's image pipeline at cdn.koolbase.com/cdn-cgi/image/<opts>/... and serves a resized, re-encoded copy of the source. Original URL behavior unchanged when transform is omitted.
  • KoolbaseStorageClient.publicUrlWithPreset({projectId, presetName, bucket, path}) and KoolbaseObject.publicUrlWithPreset(bucket, presetName) resolve a named preset stored server-side (managed via the dashboard or REST API) at cdn.koolbase.com/p/{project_id}/ {preset_name}/{bucket}/{path}. Edit the preset once on the server and every URL using it updates as the edge cache rolls over.
• Cloudflare bills unique transformations per calendar month; every Koolbase account includes 5,000 free. Transformed responses are edge-cached for 4 hours.
• No breaking changes. All new APIs are additive; existing publicUrl calls without transform produce the exact same URL they did in 6.3.0.

• feat(storage): public bucket CDN URLs (Gap #2 SDK polish).
  • KoolbaseObject gains an r2Bucket: String field identifying which physical R2 bucket holds the object's bytes. Always populated. 'koolbase-storage-public' means the object has a stable CDN URL; anything else (typically 'koolbase-storage') means it's in private storage and reads go through a presigned URL via getDownloadUrl.
  • KoolbaseObject.publicUrl(String bucketName) returns the stable https://cdn.koolbase.com/... URL for the object when it lives in the public R2 bucket, null otherwise. Use this when you have an object instance and want a safe URL — returns null rather than a URL that 404s for private or legacy public-bucket files.
  • KoolbaseStorageClient.publicUrl({projectId, bucket, path}) — static helper that builds the CDN URL pattern unconditionally. Use for build-time URL generation where you have the inputs but don't need (or want) a check that the file is actually in a public bucket.
• No breaking changes. getDownloadUrl already returns the CDN URL for objects in public buckets since the server-side Gap #2 deploy on Jun 2 2026 — this release just makes that URL constructible without a network round-trip.

• feat(storage): custom object metadata. Attach arbitrary key/value pairs to stored objects at upload time, mutate via merge semantics post-upload, read alongside any KoolbaseObject.
  • KoolbaseStorageClient.upload() gains an optional metadata: Map<String, String> named param. Set at confirm time; REPLACES prior metadata on the overwrite: true path (matches GCS semantics — a new upload at a path produces a new object, not a patch of the old).
  • New KoolbaseStorageClient.updateMetadata() method with merge semantics: keys with a non-null value are set/updated, keys with null are deleted, keys absent from the payload are untouched. One call handles add, update, and delete atomically.
  • KoolbaseObject gains a metadata: Map<String, String> field. Always non-null — {} when empty, never null — so callers can treat it as a guaranteed map without nil checks.
  • New KoolbaseStorageMetadataInvalidException (extends KoolbaseStorageException) thrown for server-side validation failures. Its detail field names the failing key and rule (e.g. key "bad key": must match [a-z0-9_]+, exceeds 50 keys (got 53)) so callers can surface actionable errors without guessing what shape rule was violated.
• Validation rules (server-side, recreated for SDK doc convenience): ≤50 keys, ≤8KB total, keys 1–64 chars [a-z0-9_]+, values ≤1024 chars, leading underscore reserved for system keys.