Use this file for stable debugging guidance only. Do not use it as a running work log.
- Reproduce the failure with a concrete command, URL, or user journey.
- Write the smallest falsifiable hypothesis.
- Run one experiment that can prove or disprove that hypothesis.
- Record verified findings in the owning GitHub issue.
- Prefer product-level smoke tests for Home, app launch, Browser, Wallet, pairing, sharing, and mobile/touch behavior.
- Prefer focused tests for the authority boundary being changed.
- Run
node scripts/check-product-data.mjsafter capsule manifest, component, model catalog, or install asset changes. Run the relevant behaviour tests after Home, Browser, provider, or authority changes. - Run
git diff --checkand Rust/JS syntax checks before handing off. - Keep historical transcripts out of active docs. Git history already preserves them.
- Debugging findings and proof belong in the owning GitHub issue. Use #89 for install and update.
- Release history belongs in
elastos/CHANGELOG.md. - Durable architecture guidance belongs in
docs/. - Stable local-debugging invariants belong here.
Provider request/response pipes must be cancellation-safe. If an HTTP caller times out or disconnects after a provider request is written, the bridge must still drain exactly one response line before the next request can read from the provider. Otherwise a later request can consume stale provider output from an earlier request.
When a standalone provider changes, deployed Home or app assets are not enough.
Rebuild the provider binary, install it under the active
XDG_DATA_HOME/elastos/bin, update components.json with the new sha256 and
size when publishing, and restart the gateway so the provider process is
respawned.
Source-home sync must install the artifact declared by each capsule's execution contract. Runtime projections need their browser tree, WASM Components need the stamped component artifact and WIT hash, and provider or content capsules need their declared provider or data artifacts. Do not synthesize a missing WASI entrypoint as a compatibility fallback. If the installed artifact does not match the manifest, treat the install as incomplete and verify the built and installed hashes before debugging Home launch behavior.
The Browser product display path is WebRTC remote display through the Runtime
Browser Engine Adapter contract. runtime_frame, diagnostic_frame,
screenshot, and image-polling routes are not product fallbacks. Debug VM launch,
adapter IPC, WebRTC signaling/media, and Runtime-scoped input receipts instead.
Browser Engine selection must be explicit at the Browser UI/API boundary. Non-KVM hosts consume a trusted Browser Engine adapter or remote engine service; they must not silently fall back to local non-isolated browser execution.
The generated browser-vm-selkies-start bridge config and installed
browser-vm-guest-control-bridge binary/script are one versioned pair. Target
refresh and preflight must fail when the rootfs bridge does not support
elastos.browser.vm-guest-control-bridge.config/v1,
control_socket_ready_timeout_ms, and control_request_timeout_ms.
People Discovery is explicit and opt-in. It projects a bounded set of signed, TTL-bound advertisements plus exact recipient contact requests and acceptances for the configured signed collaboration network. The seed/relay may help delivery, but it is never identity, contact, membership, or conversation authority.
Signed presence is separate. It is a read-only projection of verified, unexpired presence for accepted contacts and active group participants in the configured signed collaboration network and default conversation. Presence presentation is self-asserted by the signing device key; it is not identity, contact, admission, or authorization. Missing collaboration configuration yields an explicit empty, unconfigured view, and reading People must not create identity, collaboration, or transport state.
Services state is user-facing service selection, not ambient provider authority. Local service enablement and remote service subscriptions must stay separated from provider grants until a reviewed grant-management API exists.
Capability tokens belong in the Runtime/provider envelope. Provider JSON bodies must not carry duplicate token fields unless a provider explicitly validates that field as part of a reviewed protocol.
Address-bar navigation may use in-place Browser control while the active page is
healthy. If a scheme, host, or port change fails through page control, or the
active page is already a Chromium error URL, Browser must recover through
/api/apps/browser/open so Runtime reserves a fresh Exit route and the Browser
gets a fresh display session instead of reusing stale page state.
Services access request validation and delivery failure are separate API
classes. A selected remote service offer that is not tied to a connected People
record is a deterministic request-state error and must return 400. A request
that passes local validation but cannot be delivered through the service-access
transport remains 503. Keep both focused tests in the gate:
test_home_summary_reports_people_contacts_from_accepted_conversation_members
for the 400 path and
test_services_remote_exit_request_local_only_does_not_save_requested_state for
the 503 path.
Browser profile reset receipts must machine-declare the current non-protected
posture: storage_posture=principal_owned_reset_scoped_unprotected,
protected_storage=false, encrypted=false, and recoverable=false.
Manual-review packet smokes must keep draft reports fail-closed with ok=false
and must assert the current validator requirement for at least one hash-bound
redacted Mac VM screen recording artifact. Do not replace that with a generic
visual-evidence substring or weaken the no-human-evidence gate.