archy/docs/COMPANION-PERFORMANCE-HANDOFF.txt

Companion performance and Bump release handoff
Branch: companion-enhacements
Prepared: 2026-11-12

Release status: candidate source, not an approved release. This work changes the
Android app, dashboard UI, and node backend. Shipping only the APK does not fix
Bump's node-verification delay. Do not report two-phone PEERED acceptance yet.
Keep the unrelated open release checks in
post-1.8.22-regressions-20261001.md; this handoff does not close those incidents.

Node change required before the next complete Bump UAT

1. federation.sync-state accepts optional params.did. With a DID, validate it,
   require an existing non-untrusted peer, and sync ONLY that peer. Omission
   retains the all-peers operation. Invalid/unknown targets must never fall back
   to syncing everyone. This prevents a newly bumped peer waiting behind
   unrelated offline peers in the four-slot sync queue.
2. federation.list-nodes accepts fresh:true to bypass its five-second response
   cache. Companion uses it for verification; ordinary dashboard reads retain
   caching. Verify actual fresh authenticated state, not merely a saved row.
3. Ship the node backend on BOTH participating nodes before physical acceptance.
   Existing nodes ignore the new parameters: transport exchange can succeed
   while the old all-peer verification operation still stalls.
4. Run the required isolated backend tests on the release builder:
     scripts/test-backend-isolated.sh sync_selection_tests
     scripts/test-backend-isolated.sh fresh_peer_list_bypasses_cached_membership_after_removal
   Also run the relevant existing federation, FIPS dial, config and updater tests.
   Isolated execution now passes through the official runner with rootless
   Podman: targeted selection 2, fresh-list regression 1, and FIPS suite 69.
   These results cover the proposal base; the newer release integration must
   run its own checks before deployment. No backend deployment is claimed.

Companion changes

- FIPS is pinned to upstream stable 0.5.3. Native TUN ownership, bounded teardown,
  network-bound/protected UDP sockets, and stable mesh origins avoid losing
  browser sessions during Wi-Fi/mobile handover. Keep node identities and login
  state intact; do not uninstall or reset phones to upgrade them.
- Mesh Party is hidden from Companion's navigation. Dashboard Web5 Mesh remains.
- Bump exchanges observer invitations through native NFC reader/HCE roles.
  Requests use only the selected configured node origin and its session;
  redirects and automatic mutation retries are disabled. Existing local
  non-observer relationships are refused, not silently downgraded.
- Android 15+ receiving windows are listen-only. Generic NDEF polling during
  role changes previously opened unrelated HCE apps' chooser and paused Bump.
  Discovery overrides are reset before enabling reader mode. Preparation and
  server verification keep NFC quiet; closing restores normal NFC operation.
  Older Android role fallback still needs separate device compatibility UAT.
- Preview Fast/Slow/Failure remains in source behind previewEnabled=true.
  Normal navigation passes the default false, starts real NFC, and cannot
  simulate a successful peer. No preview peers are added to nodes.
- Native black/white particle animation: centred intro badge, incoming badge
  absorbed from above, wave/sphere, fluid PEERED morph released early into
  scatter/auto-close. No final stationary word or smiley. Fullscreen belongs
  ONLY to Bump's dialog; the main activity retains its original safe areas.
- Shared Companion badges use the OS square-mark positions and gradient rim.
- Exactly two Hyprgate boot-intro-animation clips: power-switch-on at logo entry
  (gain 0.55), power-hover at exchanged-invitation wave (gain 0.45). Native media
  audio, bounded preload, stopped on exit; no additional success/exit cues.
- Verification deadline becomes a retryable error instead of silently cancelling
  and leaving Connecting indefinitely. Success still requires fresh peer state.

Dashboard performance and state

- Bound HTTP/1 RPC work to four active requests, at most two background requests;
  foreground operations get priority and cancellation releases queued/active
  work. Only confirmed same-origin h2/h3 bypasses the connection budget.
- Warm visible dashboard route code sequentially while idle/online, honouring
  Save-Data and slow connections. Route pending state gives immediate feedback
  on bottom navigation and Apps, Web5, and Settings first-level tabs. Newer
  navigation wins over older slow navigation; query tabs have distinct states.
- Cloud peer discovery is bounded and cancellable. Failed peers have a short
  retry cooldown; explicit retry bypasses it. A stale request cannot overwrite
  a newer navigation or mark a cancelled peer unreachable.
- Peer folders show the first page progressively. Cached listings are bounded
  by path count and revision; image previews use a 16 MiB / 64-entry / 30-second
  in-memory blob cache, with view-owned object URLs and logout generation guards.
  Do not replay payments or paid delivery mutations to populate any cache.
- Page background assets already use immutable HTTP caching; retain the stable
  mesh origin so the browser can reuse those assets and its session state.
- Node peer HTTP clients reuse bounded idle connection pools; single-delivery,
  paid, and require-FIPS requests preserve their existing isolation/semantics.
- Node lookup failure suppression now matches upstream 0.5.3 (zero additional
  backoff). The per-attempt [1, 2, 4, 8] second pacing remains bounded. Retain
  the discovery envelope during daemon upgrades: 0.4.1 reads it directly and
  0.5.3 migrates it to lookup/rendezvous. LAN discovery remains enabled.
- FIPS updater avoids a duplicate packaged daemon competing with the managed
  service. Stable 0.5.3 was installed on the live test node separately; no full
  backend/UI candidate deployment was performed in this work session.

Evidence and acceptance limits

- Android: 73 unit tests passed, including observer APDU exchange, rejection of
  malformed/self/trusted invitations, no credential forwarding on redirects,
  fresh-contact verification, actionable timeout, particle visibility/motion,
  and early scatter. Final source APK build (including Rust, no skip) and all
  73 Android tests passed. Earlier in-place installs passed; no phone was
  attached for the final APK install.
- Physical NFC invitation transfers observed around 296–328 ms once ISO-DEP
  connected. Role acquisition/retries take additional time. These are not
  complete peering times. One phone still lacked confirmed state from its node.
- Main app layout regression was reverted and measured on the phone: top safe
  area restored from 0 to 57 CSS px; bottom from 0 to 24; tab bar raised 24 px.
- Wi-Fi return recovered around 1.43 s in one measured handover. Leaving a
  direct server LAN still took roughly 30–35 s in earlier tests; do not call
  mobile handover solved. A local upstream three-node reproducer confirms a
  stale direct edge can block a live alternative path until remote cleanup.
- Final consolidated UI run: 170 tests in 14 files passed; vue-tsc and the
  complete production build (including AIUI preparation) passed.
  Standalone native Rust: 29 tests passed (including rendezvous policy). Browser fixtures: all three engines
  passed 15 phone first-level tab checks each, and seven Cloud grid checks each
  at desktop and phone sizes (six profiles). Fixture results and route-commit
  timings are not deployed node data-ready timings.
- The pinned upstream parser accepted the final generated node configuration;
  lookup pacing, zero extra suppression, LAN and handshake assertions passed.
- Full two-phone observer creation, both PEERED completions, offline retry,
  backend deployment, final maintainer UI/sound acceptance, and USB hardware
  transport acceptance remain release checks, not completed tests.

Remaining work / release-agent checklist

[x] Execute isolated backend tests on a supported builder (2 + 1 + 69 pass).
[ ] Qualify the combined release source and deploy reviewed node backend on both
    test nodes, preserving wallets, apps and other peers.
[ ] Install the same final candidate on both phones. The last phone versions
    were Bump12 on Pixel 9a and Bump11 on Pixel 8; Bump11 lacks the timeout fix.
[ ] With two distinct signed-in nodes, test new observer creation, existing
    observer re-verification, non-observer refusal, NFC interruption, disabled
    NFC, background/cancel, and remote offline recovery. Verify both node rows,
    public keys, observer trust, fresh contact, and both animations completing.
[ ] Confirm no unrelated NFC chooser during entry, role changes or verification;
    test normal NFC behaviour after leaving Bump and older Android separately.
[ ] Repeat actual-node Apps/Web5/Settings navigation and Cloud/peer-folder load
    timings with healthy and unreachable peers, logout, rapid route changes,
    large directories, previews, and paid-file recovery without another payment.
[ ] Resolve the remaining stale-direct-path handover delay without weakening
    FIPS authentication or liveness guarantees. The reproduction is preserved
    in companion-performance/fips-stale-lan-reproducer.patch (see README.txt).
[ ] USB LAST: stable 0.5.3 does not contain MYCO's experimental USB transport.
    Review/pin the compatible upstream transport stack, native ownership and
    permissions before enabling it. Test two-phone attach, detach/fallback,
    reattach and throughput. Do not present upstream MYCO throughput as ours.
[ ] Obtain maintainer UI/UX approval. Publish reviewed source through ngit;
    accepted main/tag commits must match mirrors. No duplicate Gitea proposal.
[ ] Final public Companion release must use Android/ship-companion.sh and the
    signing/version/mirroring rules in Android/COMPANION_RELEASE.md. Local UAT
    APKs in ~/.cache/archy-fips-migration are not public release artifacts.

Observer links and transport peering

An observer relationship grants application-level federation permissions. It
records identity and allows authenticated state exchange; it does not grant
trusted access or turn a battery-powered Companion into a transit router.
Direct FIPS transport links and available relay paths are separate. More useful
reachable mesh links can improve resilience, but adding an observer row alone
must not be advertised as automatically strengthening everyone else's routes.

Publication record

Initial ngit proposal:
https://gitworkshop.dev/nevent1qqsylyfy9njwmps6rh6ewe6nyktqlvkpnec63la3vhapytugs0tvulcpz3mhxue69uhhyetvv9ujumn8d96zuer9wck3tyzw
Node implementation commit: e99d339f (included with dashboard and Companion).
No merge, UAT approval, backend deployment or public APK release is implied.
At submission origin/main remained bc48ef6b; no incoming divergence.
Direct relay HTTPS refs confirmed the same main and the initial proposal head.
The required mirror helper audit could not complete: ngit's transport attempts
encountered the pre-existing missing object f7208e17691b088b488eb170f8697aefdf9edc2a.
Full mirror parity is NOT established; resolve before public release.

November 12 follow-up: release lineage and handover candidate

The live backend on both nodes was rechecked as SHA-256
7935ac491233424d7e2edcfebb5a2c9722152f8ba55cf5c9085c50ba57093106.
The private rollout manifests identify source
4b026b33ce528f3819cce3b77bf2fae6f7e7fc55, a descendant of the initially supplied
e14e02a1252f0a76fa93601360c052cf3c057fea and installed-earlier 4c510b2124c80b8c8dedc79d51b4b7db2db52d6f.
Do not deploy a main-only build over these nodes. Local integration branch
companion-enhacements-release preserves that full lineage and applies this
proposal; qualification is in progress, not a deployment receipt.

Framework now runs official FIPS 0.5.3, like Yaya. Its managed daemon and public
identity were checked after upgrade; no private keys or app data were changed.
Known-peer Nostr rendezvous is enabled in candidate configuration: nodes
advertise public candidates, phones only look up configured identities, and
private LAN candidate sharing stays off. Static addresses remain first choice.

The separate authenticated-return-path patch passes the stale-LAN scenario
without deleting the server's old peer. Only authenticated FSP traffic can
retain a temporary return hop; unauthenticated setup cannot refresh it, invalid
ciphertext cannot clear it, and newer direct traffic wins. Two dedicated tests
and 183 existing session tests (one ignored) pass in isolated upstream runs.
This remains a private candidate, not upstream stable or physical handover
acceptance. Build instructions and provenance are in companion-performance.

Main-only mirror audit passes via origin and direct relay Git. Historical audit
remains blocked by the pre-existing dangling local v1.7.115-alpha tag; scoped
audits no longer enumerate unrelated tags. No tag was deleted or rewritten.

Private FIPS installation checkpoint (not physical handover acceptance)

Both Framework and Yaya now have package 0.5.3+archy.handoff1, candidate SHA-256
69a029196555a5d729a4c9e4448e319bc5b927cbb33859acff20fa651ea047d7.
The builder receipt records immutable image
bb3e78b4832298f4f9ce9cca8a8a8261a4faf8723eccf6df7b76adf77988b34a
and patch SHA-256
21c629bf738298697edce64096f6cb8340ee294bce9f40c0d896cd4bc4650822.
Official 0.5.3 rollback packages remain in each node's .cache/companion-update;
old binaries/config/public identity are in
/var/backups/companion-handoff1-20261112. Both managed FIPS services and TUNs
are active, existing identities verified, and the packaged duplicate service
stays masked. Three Yaya-to-Framework mesh pings passed with no loss; Framework
to Yaya mesh HTTP returned 200. These are connectivity smoke checks, not
mobile handover latency or two-phone Bump acceptance. Application backends
remain unchanged at the installed 7935ac49 hash pending integrated qualification.

Integrated source qualification: vue-tsc passes; the Cloud/rental retest passes
114 tests after resolving combined pagination behavior. Keep completed pages
on later transport failure, discard revision-invalid results, and cache only
complete listings. Shared browser fixtures pass 15 first-level tab checks per
engine on phone viewport plus seven Cloud checks for all desktop/phone engine
profiles. Chromium, Firefox and WebKit are covered; physical phone UAT is not.