Spec: the core owns the request table; shells carry one generic server request

[JacobStephens2]

Summary

The core now owns the request table. Each shell just carries one generic request.

flowchart LR
  subgraph Core[cascade-core]
    direction TB
    table[server.rs: request table<br/>path, method, body, parsing] --> route[route ServerResponse by id<br/>+ 401 rule]
  end
  Core -->|"ServerRequest { id, method, path, bearerToken?, body? }"| Adapter[one HTTP adapter per shell<br/>web · Android · Apple · Windows]
  Adapter -->|"ServerResponse { id, status, body }"| Core
  Adapter --> Server[(sync server)]

Loading

 Effect
-  PushListening · SendSignInLink · VerifySignInToken
-  RevokeSession · DeleteServerListening · DeleteServerAccount
+  ServerRequest { id, method, path, bearerToken?, body? }
 Command
-  ListeningSyncSucceeded · ListeningSyncFailed · SignInLinkSent · SignInVerified
-  ListeningDataDeleted · AccountDeleted · AccountRequestFailed
+  ServerResponse { id, status, body }      # status 0 = not sent / no response
-  DeleteListeningData · DeleteAccount
+  DeleteListeningData { newDeviceId } · DeleteAccount { newDeviceId }
-  RequestSignInLink { email }
+  RequestSignInLink { email, platform? }   # Windows sends "windows"

apps/
├── web/src/sync/carrier.ts              # fetch adapter (keepalive on pagehide flush); api.ts deleted
├── android/.../sync/ServerHttp.kt       # HttpURLConnection adapter; SyncApi.kt deleted
├── apple/CascadeShared/Sync/ServerCarrier.swift  # URLSession adapter; SyncApi.swift deleted
└── windows/Cascade/Services/SyncServer.cs        # HttpClient adapter; SyncApi.cs deleted
crates/cascade-core/src/server.rs        # the one request table
docs/adr/0001-listening-time-crdt.md     # decision 5 amended (issue #58)

• Ids come from a counter in core state that starts at 1 and is never persisted. A response with an id the core isn't waiting for changes nothing. That covers the revoke and superseded requests.
• Every request is settled, including the sign-out revoke. A shell with no sync server settles each request with status 0 up front.
• serverTotalMs is read as a signed integer and clamped at 0. A 2xx response whose body does not parse is a plain failure.
• The shell code shrinks by about 400 lines across 20 files (+463 / −871).

Evidence

• Before: the request rules lived in four shells and had no tests. On web and Android, a negative server total was rejected. On Windows, an unhandled request effect was dropped and its in-flight guard never cleared.
  After: cargo test -p cascade-core passes every suite. account has 50 tests and listening_sync has 36. New tests lock the table and the routing, for example:

  a_negative_server_total_clamps_to_zero            ok
  status_zero_and_non_401_errors_are_plain_failures ok
  a_response_with_an_unknown_id_changes_nothing     ok
  the_revokes_response_changes_nothing              ok
  an_account_request_and_a_sync_settle_in_either_order ok
  

  These also pass, as checked during review:

  • cargo check -p cascade-uniffi -p cascade-wasm
  • npm run wasm && tsc -b (web)

  The Android, Apple and Windows builds were not run in this review environment. Those shells are verified by building them and checking sign-in, sync and delete by hand, as the Spec sets out.

Merge Danger

Door: two-way

The core and all four shells move to the new wire together, and nothing persisted changes shape: request ids are never stored. Reverting the merge restores the old pair of effect and command families.

Blast Radius: accounts

Sign-in, listening sync, sign-out and both deletes go through the new adapter on every platform. A shell whose DTO drifts from the core's wire would break account features on that platform, but playback is unaffected.

Unaddressed findings

Standards

• account::Pending and account::PendingRequest names are unclear (Mysterious Name). Skipped. Both are internal to the core and their doc comments separate id + request from kind, so a rename would be churn.
• The adapters are named differently across shells (ServerHttp, ServerCarrier, SyncServer, carrier.ts), and SyncConfig lives in different places. Skipped. Each name follows its own shell's conventions, and renaming three shells we can't build here adds risk for no behaviour change.
• HTTP method is a bare string in the Android and Windows DTOs (Primitive Obsession). Skipped. The adapters pass it straight to the HTTP stack, and an enum would add deserialization plumbing on two shells that can't be built here.
• Apple makes UUID().uuidString inline in AccountControlsView rather than in a newDeviceId() helper (Duplicated Code). Skipped. These are two one-line call sites in one view, and the Apple shell can't be built here.
• Request timeouts differ by shell (web 30 s, Apple and Windows 15 s, Android 10 s). Skipped. The ADR leaves timeouts to each shell.
• Windows _dispatcher.TryEnqueue ignores a false return. Skipped. It only fails while the UI dispatcher shuts down, and at that point the core and its in-flight guards go away with the process.

Spec

• Hand checks of sign-in, sync and delete against the sync server are not evidenced. Skipped. They need each platform's device or toolchain, and this review ran headless on Linux. They're still needed before release.
• Web adds a 30 s request timeout that api.ts did not have (scope creep). Kept. Without it, a hung fetch would never be settled and would hold the core's in-flight guard forever. That would break "every request is settled".
• A 2xx verify with an empty sessionToken counts as an invalid link (scope creep). Kept. An empty token is no session, and treating it as one would persist an unusable account.
• Android types ServerRequest.method as a String. Skipped. This is the same reason as the Standards finding above.
• Windows TryEnqueue can drop a settle during shutdown. Skipped. This is the same reason as the Standards finding above.

Closes #57

Tickets

• Core: one ServerRequest effect and one ServerResponse command own the request table #58 landed with Core: one ServerRequest effect and one ServerResponse command own the request table #63
• Web shell: carry every server request through one HTTP adapter #59 landed with Web shell: carry every server request through one HTTP adapter #66
• Android shell: carry every server request through one HTTP adapter #60 landed with Android shell: carry every server request through one HTTP adapter #67
• Apple shell: carry every server request through one HTTP adapter #61 landed with Apple shell: carry every server request through one HTTP adapter #65
• Windows shell: carry every server request through one HTTP adapter #62 landed with Windows shell: carry every server request through one HTTP adapter #68

🤖 Generated with Claude Code