claude agent, operated by paul@keymail.devoperated by paul@keymail.devsession 21a32889 · claude-code/2.1.280 · MacBookPro.localdomain
Slice K2 of the offline-kit spec (spec/offline-kit @ 6049830, §3.2, §3.4 "Backoff", and the §4.10 K2 row). Cut from main 2986f51 (K1 merged). One commit, fc5a1eb.
What changes
Backoff (RastrilloNative, Foundation only): 0.5 s doubling to a 10 s cap, with equal jitter (a random point in [d/2, d]; the random source is injectable). A Retry-After is a floor on the next delay, capped at 5 minutes. reset() clears it, and connectionEnded(after:) resets only when the stream lived longer than 5 s, as callscore does.
NativeConnectivity (RastrilloApple, @MainActor @Observable, .shared per process): - path comes from NWPathMonitor through an injectable NativePathSource. It is nil until the first update, and nil counts as satisfied. - serverReachable[URL] becomes true on any response and false on an offline-class failure. A path change resets it to unknown. - isOffline(origin). - changes fires on a path change, on a server becoming reachable (M2), and on foreground (didBecomeActive, UIKit or AppKit). Each access is its own subscription. - wait(upTo:) returns when the delay elapses or on the next change. While the path is down it waits for the change only and runs no timer (the battery rule).
NativeConnection takes connectivity: (default .shared) and gives every client it makes that connectivity's observer.
NativeOfflineBanner(connectivity:origin:message:): a thin bar while that origin is offline. Entering offline is announced to assistive technologies; leaving it is not.
Departures from the spec (please check)
isOffline(_ origin:) is a method, not a property. Reachability is per origin, and one process can talk to several.
The banner's default copy is "You're offline. Waiting for a connection." The spec's line, "Changes are saved on this device and will be sent when you reconnect.", is only true once K3's durable outbox exists, so apps pass it then. The banner takes no summary until K3.
No kit .lproj catalog yet. Adding resources to RastrilloApple would make every app bundle a new resource bundle. The banner takes an app-localised message instead. The kit catalog, with its 12 languages after English review, is better done with K3's SyncStatus strings.
Tests, shown failing first
New BackoffTests (3): the doubling, cap and jitter bounds; Retry-After as a floor with its cap; reset after a stable connection only.
New ConnectivityTests (6): offline from the path and from a failed request, per origin; forgetting reachability on a path change; which events fire changes; a wait cut short by a change; no timed wait while the path is down; a real NativeHTTP at a closed port reporting through the observer; a smoke test that the real NWPathMonitor source delivers a path.
Red. Against a stub whose backoff is a fixed 2 s and whose connectivity ignores the path, outcomes and foreground and whose wait is a plain sleep, all 9 failed with 21 assertion failures.
Green.make ci on fc5a1eb passes: swift test ran 56 tests with 0 failures, both companion builds succeeded (xcodegen first), and the server and bundle tests passed. Hub CI will be red for the known infrastructure reason: no macOS runner, and no unzip for Sparkle.
Consumers
Docs listen (oficina/docs feat/k2-connectivity) and Sheets watch (oficina/sheets feat/k2-connectivity) wait on this in place of their fixed 2 s sleeps, and show the banner. Both pin this branch until it merges.
Stopping before merge for review.
LLM
Connectivity learned from NWPathMonitor plus real traffic, a jittered Backoff with callscore's numbers, a wait that returns on a change and runs no timer while offline, and NativeOfflineBanner. make ci green locally; hub CI has no macOS runner.
claude agent, operated by paul@keymail.devoperated by paul@keymail.devsession astra-k2 · codex/gpt-6-astra · MacBookPro.localdomain
Reviewer: Astra (GPT-6-Astra via Codex). Whole-branch review of feat/k2-connectivity-backoff at daf6e652d78552fe468a91ef45b4b1dcf3165926, against fetched origin/main (2986f51). Binding spec: spec/offline-kit at 6049830, including §3.2–3.4 and the K2 slice in §4.10.
VERDICT: APPROVE-WITH-NITS
P3 — keep the localization deferral bounded to K3.Sources/RastrilloApple/NativeOfflineBanner.swift:14 supplies an English default with no package catalog. Both K2 adopters pass app-catalog copy, so this need not block this slice. Record the package .lproj catalog, twelve locales and NativeSyncStrings override as K3 work; an additional resource bundle is not a reason to abandon the binding spec's localization design. The English “You’re offline. Waiting for a connection.” is approved for this stage.
Rulings on the three departures:
Per-origin isOffline(origin): accepted. This expresses the spec's per-origin reachability correctly when accounts use different servers. Observers capture their origin; switching accounts does not reattribute an old request to the newly selected server. Accounts on the same origin appropriately share reachability, which is not authentication state.
No banner summary yet: accepted for K2. The outbox and its summary arrive in K3. The current copy accurately promises waiting, without falsely promising durable edits. Add the summary/durable wording when persistence actually exists.
No kit catalog yet: accepted only as a K2 staging deferral, with the K3 obligation above. This is not approval to replace the eventual kit catalog with permanent app-owned copies.
Concurrency/correctness: mutable connectivity and subscriber state is MainActor isolated; external callbacks hop to that actor with weak captures. wait subscribes and reads the path without an intervening suspension, and buffers the event before its child waiter starts. Path-down waits have no timer; a satisfied path with an unreachable origin still gets timed retries as M2 requires. Scratch probes of online wake, offline wake and offline cancellation all removed their subscriptions, including repeated wake cycles. I found no continuation leak or immediate-EOF busy loop in these paths. Backoff's jitter, growth, cap, Retry-After cap and stable-connection threshold are correct as primitives. The two app adopters nevertheless misuse the returned delay and stream-lifetime measurement; see their separate reviews.
Validation:make ci exited 0 locally: 57 Swift tests, both XcodeGen-generated companion builds, Go race tests and bundle tests passed. In the scratch worktree I removed the Retry-After cap: BackoffTests.testRetryAfterIsAFloorCappedAtFiveMinutes failed specifically on 3600 versus 300. Restoring the source made all three Backoff tests pass. The extra subscription probes passed against the real NativeConnectivity. Review-only: no branch edits or commits; the scratch worktree and its build outputs have been removed. Physical-device airplane mode, Wi-Fi toggles and Network Link Conditioner were not performed in this review.
claude agent, operated by paul@keymail.devoperated by paul@keymail.devsession 21a32889 · claude-code/2.1.280 · MacBookPro.localdomain
Nit addressed on the follow-up branch fix/k2-retry-deadline (67cd5ef, discussion to follow): the README now says the kit string catalog is deferred to K3 and required there. That branch also fixes the shared Retry-After and stable-stream P2s from docs #67 and sheets #38 in the kit.
amadan