diff --git a/docs/reference/plans/2026-09-06-hybrid-compatibility-simplification-audit.md b/docs/reference/plans/2026-09-06-hybrid-compatibility-simplification-audit.md new file mode 100644 index 00000000000..c8287bf2c5b --- /dev/null +++ b/docs/reference/plans/2026-09-06-hybrid-compatibility-simplification-audit.md @@ -0,0 +1,160 @@ +# Hybrid compatibility simplification audit + +Audited September 6, 2026 at `6e949ece6c0`, branch `mobile-rearch`. +This is a code audit and removal plan, not an implementation change. + +## Decision + +Hybrid has no released users. Preserve released native mobile → new Desktop +compatibility. New hybrid → old Desktop may stop with the existing Update Desktop +UI. Do not support hypothetical earlier releases of this PR's hybrid shell/page. + +Keep the generic bridge and Desktop-owned product logic. Remove the duplicate +hybrid paths once the first-release baseline is enforced. No protocol bump is +needed merely to clean up an unshipped bridge; keeping its current number is fine. +After hybrid ships, its shell/page contract becomes a real compatibility boundary. + +## Findings + +### 1. Removable hybrid fallback selection + +These page clients explicitly choose a generic operation or an older hybrid bridge +operation. They do not provide the RPC surface used by released native apps. +Paths below are relative to `src/mobile-web/src/`. + +| Area | Files | Simplification | +| --- | --- | --- | +| File list/search/text/directory/chunk reads | `mobile-web-file-request-client.ts`, `mobile-web-file-read-request-client.ts` | Remove legacy closures and unsupported-host/shell fallback. Keep page-side validation, file presentation and decoding. Invalid input should fail directly. | +| Source Control status/diff | `mobile-web-source-control-read-request-client.ts` | Use generic host reads directly. Keep page presentation and bounded results. | +| Source Control watch | `mobile-web-source-control-host-subscription.ts` | Keep one host subscription; remove switching to the shell-owned subscription. Preserve cancellation, ready and cleanup. | +| Native-chat reads/feed/mutations | `mobile-web-host-native-chat-read.ts`, `mobile-web-host-native-chat-subscription.ts`, `mobile-web-host-native-chat-mutation.ts`, `mobile-web-native-chat-request-client.ts` | Require baseline host binding/forwarding. Remove legacy operation selection. Keep private-resource resolution, current-document authority and mutation deadlines. | +| Native-chat file actions | `mobile-web-native-chat-file-client.ts` | Require page tab identity for host binding; remove fallback to shell file adapters. Check all call sites before tightening the API. | +| Session agent discovery and creation | `mobile-web-session-terminal-creation.ts`, `mobile-web-session-request-client.ts` | Remove legacy callbacks and old-shell constructor default. Retain workspace injection, mutation ID, deadline and no retry after ambiguous creation. | +| Terminal clear/rename/display mode | `mobile-web-host-terminal-actions.ts`, `mobile-web-terminal-request-client.ts` | Make host metadata binding required, remove feature-selected legacy metadata actions. Keep terminal binary/input/device lanes. | + +Ten principal files in this table total 1,202 lines. That is an inspection +footprint, NOT deletable lines or an estimate of time spent: those files also +contain necessary implementation. This audit does not justify a percentage claim. + +### 2. Remove obsolete shell branches after their callers + +`mobile/src/mobile-web/mobile-web-production-grants.ts` still advertises both +host forwarding and domain-specific operations. Delete only superseded operation +entries, dispatcher branches and dead projections, not whole families blindly. + +Concrete follow-up locations: + +- `mobile-web-file-operations.ts`: superseded read/list/search operations. + File write/open/artifact operations still have active shell callers. +- `mobile-web-source-control-operations.ts` and subscription dispatch: superseded + status/diff/watch paths; other Source Control operations remain active. +- `mobile-web-native-chat-operations.ts`, `mobile-web-native-chat-subscriptions.ts` + and `mobile-web-native-chat-message-projection.ts`: superseded domain reads/feed + and mutations. Native image/clipboard/pending-delivery paths remain needed. +- `mobile-web-session-operations.ts`: superseded agentOptions/create/createAgent + branches. Snapshot/activate/close/browser/quick-command operations are still + the current implementation, not optional backward compatibility. + +`mobile-web-session-snapshot.ts` still populates browser/native-chat authorities. +Deleting it now would break active consumers. Moving those responsibilities is +additional implementation work; removing old-version tests cannot replace it. +Shared presentation/schema files must stay where the hosted page still imports them. + +### 3. Settings and first-release shell features + +The hosted Terminal route's "Open device terminal settings" alternative exists +for a shell without pagePreferences. Remove that alternative once pagePreferences +is mandatory. Apply the same review to hosted menu and session settings navigation. + +`web-terminal-preferences.ts` has two different kinds of fallback: + +- No pagePreferences capability → native-only behavior: obsolete baseline branch. +- No stored page value → inherit existing native preference: useful behavior for + a user's upgrade from native to hybrid; keep it, including explicit false/empty + value semantics and read-failure handling. + +`src/shared/mobile-web/shell-feature-contract.ts` lists five features, including +host scope, host page-session injection, dispatch guards and opaque page state. +Current implementations can become first-release requirements instead of optional +compatibility branches. Do not remove the underlying protections. Retain a small +future feature-negotiation mechanism for genuinely new native capabilities after +release; no historical emulation is needed now. + +Existing native screens and native host-operation modules also serve native build +variants and shared hosted presentation. Their mere presence does not mean an +old-hybrid fallback. `mobile-native-baseline-mode.ts` explicitly supports native +release artifacts and development comparison fixtures. Treat artifact retirement +as a separate decision, not collateral cleanup. + +### 4. Keep released native-app and remote-host compatibility + +Native clients directly call existing RPCs, demonstrated by: + +- `mobile/src/session/native-host-session-tab-operations.ts`: session.tabs.list, + session.tabs.createTerminal, session.tabs.close and browser.tabCreate. +- `native-host-session-native-chat-operations.ts`: nativeChat.readSession and file + search/list methods. +- `native-host-session-terminal-operations.ts`: terminal metadata RPCs. + +Keep their Desktop methods, accepted inputs, response fields/meaning, existing +mobile authorization and subscriptions. Retain new mobileWeb.* adapters beside +those RPCs; that is the appropriate Desktop compatibility boundary, not duplicate +hybrid client behavior. Do not raise Desktop's minimum compatible mobile version +to enforce a hybrid-only baseline. + +SSH/headless runtime compatibility also remains real. A current Desktop can target +an older remote host. Do not globally delete capability checks, transport protocol +negotiation or execution-host fallbacks based on the fact hybrid is unshipped. + +This audit traces current native call sites; it is not a released-binary cross-version +certification. A representative released native client against changed Desktop is +still the strongest validation before merge. + +### 5. Existing Update Desktop UI needs a precise baseline + +`use-mobile-web-package-capability.ts` currently tests +MOBILE_WEB_PACKAGE_RUNTIME_CAPABILITY. `use-mobile-web-package-session.ts` maps its +absence to host_update_required and "Update Orca on [host] to continue." +The general ProtocolBlockScreen also has desktop-too-old UI, but the shared native +protocol floor is not a substitute for the hybrid baseline. + +Package-serving support alone does not prove the newly required generic operation +set exists. Before removing fallback paths, require one final hybrid-baseline +capability on connection and reuse the existing update-required UI. It should +represent the actual first-release package/forwarding contract, not every future +product method. An optional future host method can remain absent in the catalog +without demanding a new APK or falling back to a removed shell translator. + +Keep native manifest verification, bridge range admission, payload ceilings and +resource authorization. These protect real execution and future released shells; +they are not historical fallback machinery. + +## Tests and documentation + +Remove/replace tests asserting successful fallback for old hybrid shells, missing +baseline host grants, and cached pages from intermediate PR versions. Examples: +`mobile-web-file-host-reads.test.ts`, `mobile-web-host-terminal-actions.test.ts`, +`mobile-web-native-chat-file-client.test.ts`, `mobile-web-session-terminal-creation.test.ts`, +and the explicitly old-shell case in `mobile-web-bridge-roundtrip.test.ts`. +Do not remove entire suites: preserve success, invalid-input, privacy, cancellation, +subscription cleanup, deadline, stale-binding and no-duplicate-mutation cases. + +Retain tolerant shell→page parsing and additive evolution tests as future contract +properties. Replace blanket "keep legacy v2/cached pages" requirements in the main +tracker and architecture policy with the actual first-release baseline. Cached +packages and existing production rollback remain; the extra crash-loop drill and +optional resume improvements stay deferred under YAGNI. + +## Recommended removal order + +1. Establish the hybrid baseline check using existing Update Desktop UI; verify + released native clients are unaffected. +2. Remove the page-side fallback selection for completed generic slices. +3. Remove now-unreachable shell operation grants/dispatch/projections after an + import/call-site check. Leave unmigrated domain operations functioning. +4. Simplify mandatory settings/feature branches and revise the relevant tests. +5. Run code gates and ordinary iOS/Android journeys; include native-client RPC + compatibility checks. Then continue the remaining domain moves directly, + without adding another historical hybrid path. + +No runtime files were changed by this audit. All removal items remain pending. diff --git a/docs/reference/plans/2026-09-06-long-lived-mobile-shell.md b/docs/reference/plans/2026-09-06-long-lived-mobile-shell.md index a720b08a854..f4523694cb3 100644 --- a/docs/reference/plans/2026-09-06-long-lived-mobile-shell.md +++ b/docs/reference/plans/2026-09-06-long-lived-mobile-shell.md @@ -14,6 +14,20 @@ A checked box means implemented and verified, with evidence below. Unit tests alone do not complete a platform journey. Keep legacy v2 paths for older cached pages; no protocol or manifest bump is planned. +## Compatibility scope correction — audit completed + +User confirmed hybrid has zero released users. Preserve released native mobile → +new Desktop behavior; hybrid → old Desktop may require a Desktop update. Earlier +entries requiring compatibility with intermediate hybrid shells/pages are +superseded by this decision, not evidence of shipped contracts. + +The [simplification audit](./2026-09-06-hybrid-compatibility-simplification-audit.md) +contains concrete removal targets and retained boundaries. Runtime cleanup has +not been performed. First establish the final hybrid baseline through the existing +Update Desktop UI, then remove completed slices’ hybrid fallbacks and their dead +shell branches. Preserve native RPCs, real SSH compatibility, page-state/storage +protections and currently unmigrated domain paths. + ## Current checkpoint Last reconciled: September 6, 2026, current host-settings integration batch.