User Flow Coverage Report

This document tracks end-to-end user coverage for Aura's runtime harness scenarios across TUI and web surfaces.

Coverage Boundary Statement

User flow coverage validates user-visible behavior and interaction wiring through runtime harness scenarios. It does not replace protocol conformance, theorem proofs, or differential parity lanes. Use this report for UI/product flow traceability and regression targeting.

The harness coverage model has two explicit lanes:

• shared semantic lane:
  • parity-critical shared flows execute through the shared semantic command plane
  • this establishes real frontend semantic integration after deterministic in-process runtime/app validation
• frontend-conformance lane:
  • renderer-specific control wiring, DOM/PTy mechanics, and shell integration are validated separately
  • these scenarios are intentionally not the primary shared-flow substrate

Coverage in this report describes frontend execution. Complete runtime/app flow regressions run first in-process using the real implementation and controlled effects. Local frontend checks follow; cross-machine P2P confirmation batches locally proven flows after checkpoint gates and main smoke. A harness coverage row does not imply simulator, fault/restart or cross-machine evidence. See Testing Guide.

Summary Metrics

Coverage Classes

Aura tracks three different coverage classes in this document:

This report is a traceability document for those classes. It is not a proof of protocol correctness, and it does not replace conformance or verification lanes.

Exact semantic expectation coverage

The harness library regressions distinguish list membership, item confirmation and explicit selection through the canonical scenario lowering and matcher. They cover missing and unrelated selections, absent members, changed confirmation, and exclusion of private lowering metadata from serialized compatibility fixtures. Focused control identity cannot establish control visibility.

Typed snapshots currently establish screen, list and modal presence. Ordinary ControlVisible expectations fail explicitly until render-bound observations exist. This includes the onboarding_root expectations in semantic-observation and frontend-conformance smoke scenarios; the matcher tests do not establish those flows. Actual native and browser render producers, source-revision binding, and paired-client execution remain required before claiming visibility coverage.

Reactive observation health

Both frontends export per-owner, per-signal UiSnapshot.subscription_health with typed attaching, healthy, degraded, and recovering states. A failed registration, closed stream, or failed snapshot read must remain observable; reattachment reads the current value before claiming healthy convergence. The shared UI and TUI library tests cover failure and recovery transitions, duplicate shell observer prevention, and snapshot serialization. The browser and TUI semantic-observation smoke scenarios remain the end-to-end anchors for startup, navigation, and ui_state convergence; they do not yet inject stream closure or runtime rebootstrap. The recovery smoke in work/8.md Task S14 must add those fault-injection cases to the PR lane.

The TUI export also carries diagnostic UiSnapshot.supervised_task_failures (group, task, cause of dead runtime-supervised tasks). It is not parity-classified, gates no readiness or quiescence, and the browser publishes it empty. Coverage is the aura-app serialization test and the aura-agent bridge accessor test; LAN runs read it with deadtasks <inst>.

Projection source revisions

UiSnapshot.projection_source_revisions reports the graph revision last copied into each observed app projection (chat, contacts, homes, invitations, recovery, and neighborhood). TUI and browser exports use the same app snapshot source. These values are separate from UiSnapshot.revision, which advances with frontend semantic or render publication. After both observers are quiescent on one runtime, their entity sets and source revisions should agree. The Task 4 transaction and mirror tests cover stale publication and delayed view-copy races; the Task 14 PR smoke must exercise this through both frontend observers after a forced stale projection and recovery.

Canonical home mode observations

Observation surface version 2 requires UiSnapshot.home_modes on both frontends. The shared app projection helper exports each materialized home's channel, context, and mode flags from the same app snapshot as its homes source revision. Missing contexts are withheld; unavailable browser app reads publish loading/busy rather than authoritative absence. Shared parity comparison checks these bindings and mode flags independently of list order.

Focused app, native terminal, and shared UI tests cover canonical projection, required wire fields, parity differences, matching homes provenance, and unavailable reads. The shared UI's real HOMES subscription-to-render-to-sink regression changes only mode flags while display values remain equal, verifies a newer homes revision in the pushed snapshot, and fails with the old render-equality gate. Subscription attachment is acknowledged before healthy publication; immediate-update and repeated-mount cancellation tests cover that ownership boundary. These are in-process observations: paired LAN mode-change publication and convergence through both frontends remain unproven.

Canonical UX Scenario Set

The TUI-only conformance scenarios and browser enrollment transfer/reopen are frontend-conformance coverage; Scenario 13 remains the shared contact/chat anchor. All harness scenarios in this inventory use the semantic scenario format.

User Flow Matrix

Current parity-critical source changes touched the following shared-flow areas and continue to map to the same canonical coverage anchors:

• Shared flow and scenario contract metadata now live behind facade roots in aura-app::ui_contract and aura-app::scenario_contract, with dedicated module families for parity metadata, harness metadata, shared-flow support, action contracts, expectations, submission, and value types. The canonical public contract and the coverage anchors below do not change with that internal split.
• Notifications navigation remains anchored by shared-notifications-and-authority.toml, with semantic-observation-browser-smoke.toml and semantic-observation-tui-smoke.toml as secondary observation coverage. The current notifications-screen change is limited to neutral empty-state copy and detail text, and the coverage expectation remains that notifications navigation exercises shared semantic navigation only rather than frontend-specific invitation or recovery actions.
• The TUI semantic-observation contract keeps the same canonical anchor in semantic-observation-tui-smoke.toml, but the native harness ingress now requires explicit harness mode, the per-run AURA_HARNESS_RUN_TOKEN, and transient-root-scoped AURA_TUI_COMMAND_SOCKET, AURA_TUI_UI_STATE_SOCKET, and AURA_TUI_UI_STATE_FILE values. That change hardens the existing observation scenario; it does not introduce a new shared-flow anchor or a production-only harness surface.
• Neighborhood navigation stays anchored by real-runtime-mixed-startup-smoke.toml
• Chat/contact navigation, the contact-to-friend lifecycle, invitation, home creation, channel join, and message-send flows stay anchored by scenario13-mixed-contact-channel-message-e2e.toml
• Contacts navigation, invitation creation, and invitation acceptance remain mapped to Scenario 13 plus the semantic observation smoke scenarios. The current terminal-side change only removes stale modal-local ownership assumptions and keeps those flows on the same typed dispatch and shared workflow path.
• Mixed contact-invite acceptance notifications now also have a dedicated symmetric mixed-runtime anchor in mixed-contact-invite-notification-roundtrip.toml. That scenario exercises TUI-create/Web-accept and Web-create/TUI-accept flows and verifies the creator-visible acceptance notification on the notifications screen without replacing Scenario 13 as the canonical contacts/chat lifecycle anchor.
• Pending channel-invitation acceptance now also requires terminal-status wrappers and *_with_instance entry points to publish a terminal failure for the same operation instance if a browser/TUI shared-flow error escapes before the owned accept path settles. That keeps Scenario 13 authoritative for contacts navigation, invitation create/accept, channel join, and shared-channel receive parity rather than leaving the lifecycle stranded at SemanticOperationPhase::WorkflowDispatched.
• aura-app splits these same flows across more specific owner modules while preserving the coverage anchors above: workflows/context/neighborhood.rs, workflows/invitation/{create,accept,readiness}.rs, and workflows/messaging/{channel_refs,channels,send}.rs. Shared-flow source metadata continues to publish through the aura-app::ui_contract facade.
• Settings/device and notifications/authority work keep the same canonical anchors. Device add/remove and shared settings remain bound to scenario12-mixed-device-enrollment-removal-e2e.toml plus shared-settings-parity.toml, while notifications navigation and authority switching remain bound to shared-notifications-and-authority.toml.
• Scenario 12 now also carries the browser-specific removable-device parity rule: the shared semantic snapshot exports current-device markers without fabricating a selected device row, so mixed browser runs must resolve remove_selected_device from the authoritative removable device in settings state when no explicit ListId::Devices selection exists.
• The browser enrollment approved-transfer/reopen scenario supplements Scenario 12 with mounted Settings import control, explicit code/manifest/independent verifier entry and approval, the original import operation's success, and same-profile restart with two retained devices. Its web_conformance classification tests browser control and persistence wiring; it does not replace the mixed-runtime parity anchor or prove threshold protocol closure.
• Scenario 13 now also carries the mixed-runtime sealed-message receive rule: the current TUI/browser shared-channel receive path may converge on sealed authoritative placeholders, so the canonical receive assertions for the mixed-runtime anchor match the [sealed: prefix instead of renderer-local plaintext recovery.
• AMP channel transition frontend observation is covered by shared semantic AMP transition scenarios plus runtime-event parity contract tests. TUI and web consume RuntimeFact::AmpChannelTransitionUpdated through UiSnapshot.runtime_events and shared aura-app::ui_contract action/control ids; the shared scenarios drive typed AMP transition fixtures through the semantic command plane and assert RuntimeEventKind::AmpChannelTransitionUpdated without frontend-specific compatibility steps.
• Browser bootstrap broker credential handling remains frontend-conformance coverage. Bearer and invitation retrieval tokens must come from session-scoped browser storage rather than URL query parameters, while the broker endpoint may still be staged through controlled bootstrap metadata. The native storage boundary test and browser observation smoke coverage protect the bridge/storage contract without creating a new shared semantic user flow.

Scenario 13 remains the canonical anchor for the shared contacts lifecycle because it exercises the parity-critical semantic controls for send friend request, accept friend request, decline friend request, and remove friend while preserving the runtime-projected relationship states contact, pending_outbound, pending_inbound, and friend across both TUI and web.

Frontend-Conformance Coverage

These scenarios are maintained outside the main shared semantic lane:

Planned Release And Update Validation Matrix

This matrix is the planned coverage target for harness-driven validation of module and OTA distribution/update behavior.

The intended rollout order is:

1. mechanism validation matrix
2. candidate-release rehearsal matrix
3. live-release promotion gates

Mechanism validation proves the lifecycle machinery itself under synthetic releases and controlled failures. Candidate-release rehearsal proves that one specific release works before promotion or real cutover.

This matrix should remain typed-lifecycle driven. It should not be satisfied by log scraping or ad hoc manual release notes.

Typed Release Validation Contract

Each planned release/update row above must map to a typed harness contract before it is counted as implemented.

These rows are intentionally semantic-lane requirements. Frontend-conformance coverage may validate renderer wiring for release screens or controls, but it does not satisfy release/update lifecycle coverage on its own.

Coverage Expectations

Shared Flow Contract Expectations

Every parity-critical shared flow should have, in code and metadata:

• a canonical shared flow identifier in aura-app::ui_contract
• a typed semantic command path on both TUI and web
• semantic action contracts with preconditions and terminal success/failure conditions
• an authoritative readiness, event, or quiescence owner for waits
• any parity exception recorded as typed metadata in aura-app::ui_contract with a reason code, scope, affected surface, and authoritative doc reference
• at least one canonical scenario reference in this report

Shared-flow scenarios must not rely on raw PTY keys, raw selector clicks, raw label matching, or incidental focus-stepping as their primary mechanics. Those behaviors belong in frontend-conformance coverage instead.

Frontend-specific flows may still have scenario coverage, but they are not part of the portability contract unless explicitly promoted into the shared contract.

PR Gate Expectations

1. Changes to global navigation, settings, chat, contacts, neighborhood, or ceremonies should have at least one impacted canonical scenario updated or re-validated.
2. Changes that affect both TUI and web behavior should be validated against parity-critical scenarios in the shared semantic lane on both runtimes.
3. Changes to mixed-instance behavior should include scenario 12 and/or 13 coverage.
4. Contacts-surface changes that alter relationship state or action availability must preserve the shared semantic lifecycle for contact, pending_outbound, pending_inbound, and friend, and they must stay anchored to Scenario 13 rather than shell-specific smoke coverage.
5. Mixed-runtime code exchange and chat routing changes should preserve the event-driven contract used by scenarios 12 and 13: invitation/device codes come from typed runtime-event payloads, and chat assertions bind to the selected shared channel rather than frontend-specific ordering.
6. Browser shared-flow bridge changes should preserve the explicit runtime identity staging handoff and the page-owned semantic command queue used by the Playwright lane. Coverage remains anchored in the shared semantic scenarios rather than DOM-driving fallback mechanics.
7. Changes to renderer-specific control wiring should add or update frontend-conformance coverage rather than weakening the shared semantic lane.
8. Browser bootstrap broker credential changes must preserve the rule that bearer and invitation retrieval tokens are not URL parameters, and should update frontend-conformance tests or documentation when the storage boundary changes.
9. Changes to OTA or module release/update architecture should update the planned release/update matrix above when they add, remove, or reorder mechanism-validation or release-rehearsal coverage.

CI Enforcement

Fast CI currently uses two separate gates:

• just ci-user-flow-coverage enforces traceability heuristics between changed user flow-facing source files, canonical scenarios, and this report
• AURA_ALLOW_FLOW_COVERAGE_SKIP=1 is a local-only escape hatch. CI rejects it.
• just ci-user-flow-policy enforces documentation and contributor-guidance updates for shared user flow contract and determinism surfaces via Aura's toolkit/xtask user-flow guidance sync check
• OTA and module release/update validation rows in this report are part of that same user-flow guidance surface and must be kept in sync as the release matrix evolves
• The release/update rows are expected to land in staged order: mechanism validation first, candidate rehearsal second, and promotion-gate coverage last
• just ci-harness-matrix-inventory enforces that scenario classification drives the TUI/web matrix lanes
• shared semantic scenarios and frontend-conformance scenarios are expected to remain distinct classifications. CI policy should reject shared-flow drift back to renderer-driven mechanics.

Current limitation:

• ci-user-flow-coverage still infers some ownership from filenames and does not yet prove that the correct scenario set changed
• docs updates and coverage traceability are distinct concerns. This report should not claim stronger behavioral enforcement than CI actually provides.

Residual Risk Areas

References

• Testing Guide
• toolkit/xtask user-flow guidance sync check
• Simulation Guide
• Verification Coverage Report
• Project Structure

Noninteractive native startup provider coverage

LAN tooling explicitly configures filesystem secure storage for isolated production harness profiles; runtime admission retains the harness requirement. Required driver fixtures verify that configuration reaches the child process and reject requests after shutdown. Platform retrieval unit coverage verifies exact-location missing-record classification and retained native provider failures without touching OS credentials. TUI account reload must retain native agent causes and reach authoritative ready/settled state after account creation; compile success and the pre-reload success operation alone are insufficient. See docs/804_testing_guide.md for the provider and live-run procedure.

Renderer visibility coverage adds first-producer onboarding observations from actual native canvas drawing and browser registered-node/post-flush rendering. Required regressions cover hidden/zero-clipped layout, disposal, same-semantic source rerender/remount, stale capture refusal, final AppCore source mismatch, and duplicate control-instance preservation. These regression declarations are source-only until the native/browser gates execute; paired LAN control visibility and the remaining complete control inventory remain unproven.

Modal focus observation retains the exact canonical ControlId::Field(FieldId) from the active modal field. A generic modal-input identity cannot replace that field and focus does not prove rendered visibility. The unused invitation-type list/field and generic modal-input wire variants are removed with their raw-key selector/fallback paths; no compatibility decoder remains. Actual native and shared UI snapshot regressions cover all four contact-invitation fields. These are local observation checks, not paired-client business completion evidence.