Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

User Flow Harness

This document defines the harness contract for parity-critical user flows. It supplements Testing Guide. Crate placement follows Project Structure.

1. Purpose

aura-harness is the multi-instance orchestration crate for end-to-end Aura validation. It starts local, browser, and SSH-backed instances. It runs shared scenarios against real frontends instead of renderer-specific scripts.

Complete runtime and app workflow correctness is established first by deterministic in-process execution of the real implementation. The harness owns real frontend integration evidence, including renderer and platform boundaries. Cross-machine P2P evidence is a final batched integration scope. Models and mock projections cannot replace actual protocol execution; simulator results cannot replace real frontend evidence. Validation scheduling is defined in Testing Guide.

2. Execution Lanes

The harness defines two execution lanes:

  • Shared semantic lane: submits typed intent commands and waits on typed semantic contracts.
  • Frontend-conformance lane: validates renderer-specific wiring such as PTY keys, DOM selectors, focus movement, and control bindings.

See Testing Guide for lane selection and execution details.

3. Scenario Sources

The scenario source of truth is aura-app::scenario_contract. Scenario taxonomy:

  • Shared semantic scenarios: typed semantic steps, no execution_mode declaration, no renderer-specific mechanics.
  • Frontend-conformance scenarios: typed UiAction mechanics (key presses, text input, modal dismissal), must declare execution_mode explicitly.
  • Compatibility fixtures: quarantined renderer-mechanic coverage only, must declare execution_mode = "compatibility" or execution_mode = "agent".

Inventoried scenarios are classified in scenarios/harness_inventory.toml as shared, TUI conformance, or web conformance.

See Testing Guide for scenario authoring and governance.

4. Backend Model

The harness defines the following backend interfaces:

  • InstanceBackend: lifecycle, health checks, snapshots, log tails, and basic input.
  • RawUiBackend: renderer-driven actions for conformance coverage.
  • SharedSemanticBackend: shared_projection(), submit_semantic_command(), and projection-event waits. Implemented by LocalPtyBackend and PlaywrightBrowserBackend.
  • SshTunnelBackend: orchestration-only (SSH security defaults and tunnel setup).

See Testing Guide for backend implementation.

5. Observation Model

UiSnapshot is the authoritative observation surface for parity-critical flows. Observation contracts:

  • Snapshots carry ProjectionRevision, separate projection_source_revisions for observed entity signals, quiescence state, selections, lists, operations, toasts, and runtime events. The source revisions identify graph values copied into the app view; ProjectionRevision tracks frontend semantic and render publication.
  • Parity-critical waits bind to typed contracts (readiness, visibility, events, quiescence, operation handles, strictly newer projections). Raw text matching and DOM scraping are diagnostics only.
  • Reactive refresh may combine a burst of signal updates into a later current-state projection. A wait for convergence checks the authoritative state and a strictly newer projection or declared barrier; it does not require every intermediate signal value or projection revision to be observed.
  • Frontend subscription health distinguishes attaching, ready, recovering, and failed observation for the active runtime generation. A missing signal or closed stream cannot be reported as ready; recovery attaches a new receiver and resnapshots current state before the frontend reports convergence.
  • Browser generation replacement and TUI remount cancel old observers before the new generation is ready. Harness waits bind to the active generation and treat stale-generation projections as stale even when their contents look plausible.
  • Observation paths are side-effect free. Reads do not repair state or retry hidden actions.

See Testing Guide for observation patterns.

6. Semantic Command Plane

Shared commands are typed IntentAction requests (account creation, device enrollment, contact invitations, channel membership, chat sends). Contracts:

  • Each command returns a typed response with submission metadata and an optional operation handle.
  • Post-action waits require a strictly newer authoritative projection or another declared barrier.
  • Unsupported semantic commands fail closed. No silent fallback to renderer-specific behavior.
  • ExportDeviceEnrollmentSetup returns an immediate typed DeviceEnrollmentSetup { setup_code } value from the runtime's bounded signing export. It has no ceremony operation handle. Native and browser adapters transfer the exact code; missing runtime or signing readiness rejects export rather than manufacturing identity evidence.
  • Enrollment code issuance and enrollment completion are separate operation instances. A code-ready response confirms only issuance. Wait for the ceremony-linked completion instance and its authoritative terminal state before asserting that another device joined.
  • OperationSnapshot exports the instance ID, state, and stable failure domain/code on both frontends. A cancelled operation remains distinguishable from a failure. Shared waits use those fields and the active observation generation; local wizard state, a toast, a click, or a changed count cannot substitute for a terminal result.
  • A staged browser import or bootstrap handoff reports staging. The follow-up operation settles only after the runtime ceremony outcome is observed.
  • Guardian acceptance uses a distinct follow-up operation. It succeeds only after the principal's verified binding acknowledgment; local acceptance or a click is not a terminal result.

See Testing Guide for semantic command usage.

7. Scenario Execution

ScenarioExecutor enforces per-step budgets and an optional global budget. Contracts:

  • Shared scenarios must declare convergence barriers before the next typed intent when the flow requires one.
  • The executor records canonical trace events, state transitions, and step metrics.
  • Frontend-conformance scenarios produce traces and diagnostics but are not the primary parity oracle for shared business flows.

See Testing Guide for scenario execution details.

8. Determinism And Replay

Determinism contracts:

  • Configuration validation is config-first: invalid inputs fail before execution starts.
  • Determinism derives from build_seed_bundle() (run seed, scenario seed, fault seed, per-instance seeds). Event streams use monotonically increasing identifiers.
  • Replay bundles store run config, tool API version, action log, routing metadata, and seed bundle. Deterministic shared flows preserve semantic trace shape under identical inputs.

See Testing Guide for determinism and replay details.

9. Runtime Substrate

The harness supports real and simulator runtime substrates. The existing harness command default is real; that command default does not determine development validation order. The simulator substrate is a deterministic runtime controller for fault injection and transcript capture.

Simulator substrate runs currently support local instances only. Browser instances are not allowed in simulator mode. Runtime/app flow evidence, local frontend-conformance evidence and cross-machine integration evidence retain distinct scopes. Shared actions and expected outcomes come from the app contract; missing complete-flow simulator coverage remains explicit until implemented. No browser simulator support is implied by this contract.

10. Governance And Policy

Harness governance is typed first. aura-harness exposes governance checks for shared scenario contracts, scenario-shape enforcement, barrier legality, user-flow coverage, UI parity metadata, and wrapper integrity.

The main repository policy entry points are Aura's toolkit/xtask checks exposed through just ci-shared-flow-policy, just ci-user-flow-policy, and just ci-harness-matrix-inventory.

Harness mode may add instrumentation and render-stability hooks. It must not change parity-critical business semantics. Allowlisted exceptions must carry owner, justification, and design-note metadata.

11. Boundaries

aura-harness is tooling. It is not the authority for domain semantics, effect traits, or protocol safety rules. Those contracts remain owned by aura-core, aura-app, and the other runtime and specification crates.

The harness drives instances through process boundaries and typed tool surfaces. It must not mutate protocol state out of band. Shared UX identifiers, parity metadata, and observation shapes remain owned by aura-app::ui_contract.

Enrollment manifest transfer surface

ImportDeviceEnrollmentCode takes an enrollment code plus explicit signed manifest and independently transferred initiator verifier inputs. Its submission is a device_enrollment operation handle. The shared fields are DeviceImportCode, DeviceImportManifest, and DeviceImportInitiatorVerifier; browser DOM identifiers are aura-account-import-code-input, aura-device-import-manifest-input, and aura-device-import-initiator-verifier-input. Import requires a real provisional runtime with its actual exported setup signing context. Received invitation identities cannot create or replace this runtime before verification.

DeviceEnrollmentCodeReady carries the actual issuer's manifest/verifier transfer alongside the enrollment code. Capturing event variable name also captures name_manifest and name_initiator_verifier. Shared scenarios pass all three explicitly. Missing event payload fails rather than consulting the clipboard or reconstructing trust from the enrollment code. Legacy pending-code records cannot replay an enrollment without owned authenticated transfer evidence.

Native semantic failure codes

Shared semantic operation errors preserve the operation failure domain and native failure code across frontend and harness snapshots. Required native categories map to crypto_failure, serialization_failure, storage_failure, journal_failure, or reactive_failure. Generic crypto failure does not assert unauthorized access or signature denial. All frontends and harness observers consume this canonical shared error contract; display text is not category evidence.

Typed command failure classification

Strong-command terminal outcomes classify typed resolver/precondition/plan failures and native runtime error categories. The display text of generic Invalid or PermissionDenied failures cannot manufacture a more specific semantic subreason. A membership/mute/ban result requires an originating typed domain reason; generic denial remains permission_denied.

Typed moderation decisions

A command's not_member, muted, or banned code requires the corresponding typed moderation decision retained from the authoritative status query. Send/join operations retain the exact queried context/channel/authority. Generic permission text cannot supply those codes. The existing owned send failure boundary publishes moderation denial before returning its original source chain.

Enrollment import success requires the actual independently pinned issuer committed confirmation, durable original-window acknowledgement and sanctioned exact-generation adoption. Frontends receive an opaque completion with receipt locator fields; they cannot reconstruct completion from persisted JSON or subject/device IDs. A profile handoff or restart must revalidate the runtime's original durable receipt before publishing the selected identity. Persisting selection, account configuration and pending-state cleanup separately does not satisfy this profile transaction contract.

Required flow-budget guard denial has the stable budget_exceeded native and semantic category. It remains distinct from authorization denial and retains the structural required/remaining policy reason. Frontends and harness observers do not infer either category from operation text or automatically retry it.

Bootstrap account operation continuity

Runtime-free account creation transfers its original operation instance to the application owner before storage production. A successful terminal outcome requires acknowledgment of both pending bootstrap and account configuration. The first runtime attachment preserves that original authoritative operation history. Frontend-local observations and pending-file reconciliation cannot mint account creation success. Shared parity compares that retained terminal outcome across terminal and browser surfaces.

An enrollment signing intent is identification data. Receiving, displaying, or parsing it does not approve signing. Local consent binds the original runtime and exact v4 five-domain intent, including its original issuer return mailbox statement and finite conditional negative terminal policy. Historical consent cannot be upgraded to new control authority; the policy alone cannot establish a negative decision or terminal success. A pending code-issuance outcome is distinct from committed enrollment and activation, and shared scenarios cannot infer the latter from code export. When a shared scenario performs setup and then imports enrollment under the same operation ID for one actor, it captures the setup operation instance before import and requires a different instance for terminal completion. For an actor with no prior enrollment operation, the scenario establishes that absence before import and then observes that actor's own successful operation. Neither a prior setup success nor another actor's result establishes import success. An operation wait first requires the selected actor's semantic snapshot to contain the requested operation ID and state, with a fresh instance when one was specified. If that actor also has a matching submitted handle, the wait additionally requires the handle's exact instance and state; a handle alone cannot supply missing snapshot evidence.