bitchat-android/docs/test-implementation-plan.md

Test implementation plan

Objective

Build enough deterministic, adversarial, integration, and device-level coverage that the Android client can be rewritten from scratch without silently changing its wire behavior, security properties, delivery semantics, lifecycle behavior, or user-visible workflows.

The canonical compatibility requirements are documented in client-rewrite-contracts.md. This plan describes how to turn those requirements into a complete, continuously enforced test program.

Status legend

• Complete: acceptance criteria are met and the tests run in the rewrite gate.
• In progress: implementation has started but acceptance criteria are not met.
• Not started: no implementation work has been completed.
• Blocked: progress requires an external dependency, device, or decision.

Current progress

Milestone	Status	Progress	Depends on
0. Compatibility baseline	Complete	100%	—
1. Coverage and deterministic test infrastructure	Not started	0%	0
2. Adversarial protocol and parser testing	Not started	0%	1
3. Noise, cryptography, and identity testing	Not started	0%	1
4. BLE, Wi-Fi Aware, and transport lifecycle testing	Not started	0%	1, 3
5. Sync, routing, and store-and-forward testing	Not started	0%	1, 4
6. Nostr and Tor integration testing	Not started	0%	1, 3
7. Android lifecycle and permission testing	Not started	0%	1, 4
8. Persistence, migration, and recovery testing	Not started	0%	1, 3
9. UI, media, and accessibility testing	Not started	0%	1, 7, 8
10. Physical-device and cross-client release gate	Not started	0%	2–9

Milestone completion is currently 1 of 11 milestones (9%). This is milestone-based progress, not line or branch coverage. Milestone 1 will establish measured coverage baselines and trends.

Test levels and execution policy

Level	Purpose	Expected execution
Pure JVM unit tests	Protocols, state machines, crypto vectors, parsing, routing, and deterministic utilities	Every pull request
Property and fuzz tests	Malformed inputs, boundary exploration, invariants, and crash resistance	Bounded set on every pull request; extended corpus nightly
Robolectric tests	Android services, lifecycle, broadcasts, permissions, persistence, and process recreation	Every pull request where stable
Instrumented emulator tests	Compose semantics, navigation, database/filesystem integration, and permission flows	Main branch and release candidates
Physical-device tests	BLE, Wi-Fi Aware, radios, background execution, and manufacturer-specific behavior	Nightly where devices are available; mandatory release gate
Cross-client interoperability	Android/iOS and old/new client wire compatibility	Mandatory release gate

Global rules

• Keep literal golden vectors for externally visible bytes and hashes.
• Run all compatibility and regression tests through ./gradlew clientRewriteContractTest.
• Prefer public behavior and stable adapter interfaces over implementation details.
• Require deterministic clocks, randomness, dispatchers, storage, and transports in tests.
• Never use production relay or internet availability as a test dependency.
• Every fixed protocol or security defect must receive a regression test.
• Every decoder must have positive, boundary, malformed, and fuzz coverage.
• Every asynchronous test must have bounded completion and must not use arbitrary sleeps.
• Test failures must preserve seeds, inputs, and traces needed to reproduce the failure.
• Golden vectors may change only with an intentional protocol version change and coordinated interoperability review.

---

Milestone 0: Compatibility baseline

Status: Complete
Progress: 100%

Scope

Establish executable rewrite contracts for the most important deterministic wire formats and reuse the existing regression suite as a single acceptance gate.

Completed checklist

• Create an isolated workspace and codex/client-rewrite-contract-tests branch.
• Add literal v1 and v2 outer packet vectors.
• Add public, private, optional-field, and encrypted message vectors.
• Add private-message, Noise envelope, fragment, sync, identity, and file transfer vectors.
• Add padding, binary encoding, geohash, gossip, packet ID, GCS, and Noise peer-ID contracts.
• Add Bech32, secp256k1, NIP-01, NIP-44, and NIP-13 contracts.
• Add required-prefix and representative truncated-input rejection tests.
• Add explicit validation for malformed fragment IDs.
• Add clientRewriteContractTest as the complete rewrite acceptance task.
• Verify 32 new tests pass without skips.
• Verify the full gate discovers 254 tests with zero failures or errors.
• Document the remaining device-only acceptance requirements.

Acceptance criteria

• The original main workspace remains unchanged.
• All new golden-vector tests pass.
• The complete unit suite passes through one documented command.

---

Milestone 1: Coverage and deterministic test infrastructure

Status: Not started
Progress: 0%

Goal

Make coverage measurable and provide reusable deterministic seams so later milestones test behavior without real time, radios, network access, or flaky scheduling.

TODO checklist

Coverage reporting

• Add JaCoCo or Kover for JVM unit-test line and branch coverage.
• Generate XML and HTML reports from the rewrite acceptance task.
• Record the initial project-wide line and branch coverage baseline.
• Record package-level baselines for mesh, noise, nostr, service, services, sync, model, protocol, identity, and ui.
• Publish coverage artifacts in CI.
• Add a changed-lines coverage check for new production code.
• Add non-regression thresholds without forcing low-value tests for trivial generated or platform glue.
• Exclude generated code, Compose compiler output, Android resource classes, and vendored cryptographic code from first-party coverage metrics.

Deterministic seams

• Introduce an injectable monotonic clock and wall clock.
• Introduce injectable secure and non-secure random-byte sources where deterministic vectors are required.
• Introduce injectable coroutine dispatchers and test scopes.
• Introduce an in-memory key/value storage adapter for preferences.
• Introduce an in-memory file store with controllable I/O failures.
• Define a fake mesh transport that can connect, disconnect, delay, drop, duplicate, corrupt, reorder, and fragment packets.
• Define fake BLE scanner, advertiser, GATT client, and GATT server adapters.
• Define a fake Wi-Fi Aware session/socket adapter.
• Define a fake Nostr relay transport or MockWebServer fixture.
• Provide reusable packet, identity, peer, graph, and message fixture builders.
• Provide seed capture and reproduction helpers for randomized tests.
• Add test naming and directory conventions for unit, property, Robolectric, instrumented, and interoperability suites.

Acceptance criteria

• One command generates a repeatable coverage report.
• Two consecutive clean runs produce identical deterministic test results.
• Fake time and transport behavior require no wall-clock sleeps.
• CI publishes coverage and test-result artifacts.
• The plan's progress table is updated with measured baseline numbers.

---

Milestone 2: Adversarial protocol and parser testing

Status: Not started
Progress: 0%

Goal

Prove that all wire decoders preserve canonical behavior, reject unsafe input, and never crash or allocate unreasonable memory for attacker-controlled data.

TODO checklist

Outer packet protocol

• Test every valid flag combination for v1 and v2.
• Test exact minimum and maximum payload sizes.
• Test sender and recipient IDs at 0, 1, 7, 8, 9, and oversized lengths.
• Test signatures at 0, 1, 63, 64, 65, and oversized lengths.
• Test route counts at 0, 1, 254, 255, and truncated route entries.
• Test unknown message type values remain safely representable or are rejected according to the protocol contract.
• Test invalid versions, reserved flags, integer overflow, and unsigned length conversion.
• Test trailing bytes and concatenated frames explicitly.
• Test padding boundaries around 256, 512, 1024, and 2048 bytes.
• Test malformed PKCS#7 tails and ambiguous unpadded frames.
• Test raw DEFLATE and zlib-header compatibility vectors.
• Test forged original-size fields, compression bombs, and truncated compressed streams.
• Add encode/decode property tests for all valid packet shapes.
• Add a mutation corpus derived from every golden packet.

Inner payloads and TLVs

• Fuzz BitchatMessage.fromBinaryPayload.
• Fuzz IdentityAnnouncement.decode.
• Fuzz AuthenticatedPeerState.decode.
• Fuzz PrivateMessagePacket.decode.
• Fuzz NoisePayload.decode.
• Fuzz BitchatFilePacket.decode.
• Fuzz FragmentPayload.decode.
• Fuzz RequestSyncPacket.decode.
• Test missing, duplicated, reordered, unknown, and zero-length TLVs.
• Test truncated headers and values at every byte offset.
• Test UTF-8 ASCII, multi-byte, combining-mark, emoji, invalid-byte, and maximum-byte-length cases.
• Test 255-byte one-byte-length boundaries.
• Test 65,535-byte two-byte-length boundaries.
• Test four-byte file content lengths and impossible content declarations.
• Test fragmented file content using one and multiple content TLVs.
• Define and test whether non-canonical but tolerated inputs re-encode canonically.

Fuzzing operations

• Select a JVM-compatible property/fuzz framework.
• Add bounded pull-request fuzz runs with fixed seeds.
• Add extended randomized nightly runs.
• Store minimized failing inputs as regression fixtures.
• Assert no decoder throws for arbitrary byte arrays.
• Assert decoder runtime and allocations stay within configured bounds.

Acceptance criteria

• Every externally reachable decoder has boundary and malformed-input tests.
• Every decoder has a bounded arbitrary-byte no-crash property.
• All discovered crashes or ambiguous contracts have regression fixtures.
• Extended fuzzing completes nightly and preserves reproduction seeds.

---

Milestone 3: Noise, cryptography, and identity testing

Status: Not started
Progress: 0%

Goal

Prove confidentiality, authenticity, identity binding, replay behavior, session replacement, rekeying, and recovery across the complete secure-channel lifecycle.

TODO checklist

Known vectors and primitives

• Add known Curve25519 key agreement vectors.
• Add known Ed25519 signing and verification vectors.
• Add known BIP-340 verification vectors.
• Add known HKDF and channel-key derivation vectors.
• Add external Noise XX handshake transcript vectors where compatible.
• Add deterministic channel encryption vectors with injected nonces.
• Test constant-time verification APIs where the underlying library exposes an appropriate contract.

Noise session lifecycle

• Test initiator and responder handshakes without manager wrappers.
• Test all valid handshake state transitions.
• Test every invalid message for every handshake state.
• Test tampered handshake messages and remote static-key substitution.
• Test post-handshake encryption in both directions.
• Test empty, small, maximum, and fragmented plaintext.
• Test tampered ciphertext, nonce, tag, and associated data.
• Test replayed ciphertext.
• Test skipped, duplicated, and out-of-order transport messages.
• Test send and receive nonce progression.
• Test nonce exhaustion and counter-overflow behavior.
• Test rekey thresholds, successful rekey, failed rekey, and simultaneous rekey.
• Test session reset and destruction zeroize or discard sensitive state as designed.
• Test handshake timeouts and stale generation leases with fake time.
• Test simultaneous initiator tie-breaking across a larger peer matrix.
• Test process restart with and without persisted identity.

Identity and downgrade protection

• Test peer-ID derivation for valid and malformed static keys.
• Test signing-key rotation with authorized and unauthorized announcements.
• Test private-media capability pinning across restart.
• Test downgrade attempts after a capability has been pinned.
• Test corrupted, missing, partially written, and legacy identity storage.
• Test atomic clearing of identity, capability, and peer mappings.
• Test verification fingerprints remain stable for unchanged identities.
• Test identity replacement does not expose an established session before authentication completes.

Acceptance criteria

• Known vectors pass independently of Android storage and services.
• Replay, tampering, downgrade, and identity-substitution tests all fail closed.
• All timeouts and rekey tests use fake time.
• No sensitive test fixtures contain production keys or user data.

---

Milestone 4: BLE, Wi-Fi Aware, and transport lifecycle testing

Status: Not started
Progress: 0%

Goal

Verify connection state machines and packet delivery across unreliable Android transports without requiring real radios for the majority of cases.

TODO checklist

BLE discovery and connection

• Test scan start, stop, restart, and failure callbacks.
• Test advertising start, stop, restart, and failure callbacks.
• Test Bluetooth-off and Bluetooth-on recovery.
• Test duplicate scan results and rapidly changing peer addresses.
• Test connection success, rejection, timeout, and cancellation.
• Test simultaneous inbound and outbound connection races.
• Test canonical connection selection and duplicate-link teardown.
• Test service discovery failure and missing characteristics.
• Test GATT disconnect during discovery, negotiation, read, and write.
• Test reconnect backoff with fake time.
• Test maximum-connection enforcement and eviction policy.
• Test RSSI thresholds and power-mode transitions.

Packet transfer

• Test MTU negotiation at minimum, normal, and maximum values.
• Test partial writes and write callbacks delivered out of order.
• Test notification subscription and notification failure.
• Test queue backpressure and bounded memory use.
• Test fragmentation and reassembly across disconnect/reconnect.
• Test duplicate, missing, reordered, and corrupted fragments.
• Test cancellation cleans pending queues and transfer state.
• Test large file/media transfers under constrained MTU.
• Test broadcast and directed packet delivery.
• Test packet relay while one link disconnects.

Wi-Fi Aware

• Test feature unavailable and permission-denied behavior.
• Test publish/subscribe session creation and teardown.
• Test provisional link authentication and canonical promotion.
• Test socket replacement and stale-socket rejection.
• Test partial reads, writes, EOF, exceptions, and cancellation.
• Test reconnect and rediscovery.
• Test coexistence with BLE for the same peer.

Unified transport behavior

• Test peer-list union and removal across transports.
• Test preferred-transport selection.
• Test transparent failover between BLE and Wi-Fi Aware.
• Test duplicate packet suppression across transports.
• Test transport bridge TTL decrement and loop prevention.
• Test shutdown cancels all jobs, scans, advertisements, sockets, and queues.

Acceptance criteria

• Transport state-machine tests run deterministically on the JVM or Robolectric.
• Disconnect and cancellation tests leave no queued work or active jobs.
• Cross-transport duplicate delivery and loops are prevented.
• A smaller physical-device suite confirms the fake adapters match Android behavior.

---

Milestone 5: Sync, routing, and store-and-forward testing

Status: Not started
Progress: 0%

Goal

Verify eventual delivery, bounded resource usage, correct routing, and duplicate suppression during partitions, topology changes, and reconnects.

TODO checklist

Packet identity and sync filters

• Add more packet-ID vectors for every message type.
• Prove TTL, route, recipient, and signature mutations do not change sync identity.
• Prove payload, sender, timestamp, and type mutations do change identity.
• Property-test GCS encode/decode membership.
• Test empty, singleton, maximum-capacity, duplicate, and collision-heavy filters.
• Test false-positive behavior statistically against configured tolerances.
• Test maximum accepted filter bytes and malicious bitstreams.
• Test sync requests with unknown TLVs and future capability extensions.

Store and forward

• Test caching decisions for public, private, favorite, and offline peers.
• Test cache capacity and deterministic eviction.
• Test cache expiry with fake time.
• Test delivery acknowledgement removal.
• Test retransmission after reconnect.
• Test duplicate acknowledgements and late acknowledgements.
• Test process restart persistence policy.
• Test shutdown and cleanup under active delivery.
• Test memory bounds under repeated undeliverable messages.

Routing and topology

• Test shortest paths for disconnected, cyclic, diamond, and changing graphs.
• Test deterministic tie-breaking for equal-length routes.
• Test only confirmed edges are used.
• Test edge expiry and peer disappearance with fake time.
• Test a route invalidated between planning and send.
• Test relay TTL exhaustion at every hop.
• Test source-route loop rejection.
• Test broadcast storm suppression.
• Test delivery across mixed BLE and Wi-Fi Aware paths.
• Test graph updates while sync and relay operations run concurrently.

Acceptance criteria

• Partition/reconnect scenarios eventually deliver exactly once at the application layer.
• Cache, graph, and filter resource bounds are enforced.
• No topology or bridge scenario produces an infinite relay loop.
• All expiry behavior uses fake time.

---

Milestone 6: Nostr and Tor integration testing

Status: Not started
Progress: 0%

Goal

Verify relay communication, subscriptions, event validation, NIP-17 delivery, and Tor-mode behavior under realistic network failures.

TODO checklist

Relay protocol

• Add a scripted local WebSocket relay fixture.
• Test initial connection and clean disconnect.
• Test DNS, TCP, TLS, WebSocket, and protocol failures.
• Test reconnect backoff and cancellation with fake time.
• Test relay notices, acknowledgements, end-of-stored-events, and malformed messages.
• Test subscription creation, replacement, unsubscribe, and reconnect restoration.
• Test duplicate, delayed, reordered, and conflicting events.
• Test multi-relay publish success, partial success, and total failure.
• Test event deduplication across relays.
• Test relay-list selection and invalid relay URLs.

Event security and messaging

• Add external NIP-01, NIP-13, NIP-17, and NIP-44 vectors.
• Test invalid event IDs and signatures are rejected before dispatch.
• Test future timestamps, stale timestamps, and integer boundaries.
• Test NIP-17 gift-wrap signer/rumor identity mismatches.
• Test malformed seals, wrong recipients, and tampered ciphertext.
• Test private-message and acknowledgement embedding/extraction.
• Test geohash note, presence, and ephemeral-event filters.
• Test nickname and teleport tags.
• Test proof-of-work policy at exact difficulty boundaries.
• Test cancellation and bounded mining iterations.

Tor behavior

• Add a fake Tor-state provider and proxy-selection tests.
• Test direct, Tor-only, and fallback modes.
• Test bootstrap delay, bootstrap failure, proxy failure, and shutdown.
• Verify Tor-only mode never silently uses a direct connection.
• Verify mode changes rebuild clients and close old connections.

Acceptance criteria

• Nostr integration tests require no public relay or internet connection.
• Invalid or unauthenticated events never reach application state.
• Reconnect restores intended subscriptions without duplicate delivery.
• Tor-only policy fails closed.

---

Milestone 7: Android lifecycle and permission testing

Status: Not started
Progress: 0%

Goal

Verify the app behaves correctly under Android process, service, permission, Bluetooth, battery, and background-execution rules.

TODO checklist

Foreground service

• Add Robolectric tests for service create, start, bind, unbind, and destroy.
• Test repeated start commands are idempotent.
• Test foreground notification creation and channel configuration.
• Test explicit shutdown clears transport and application state correctly.
• Test unexpected process/service recreation restores required state.
• Test task removal behavior.
• Test boot-completed handling.
• Test service start restrictions and failure reporting.
• Test all coroutines and resources are cancelled on destroy.

Permissions and system state

• Test first-run permission explanations.
• Test denial, permanent denial, and later grant.
• Test partial Bluetooth permission grants by Android version.
• Test location-disabled and Bluetooth-disabled states.
• Test notification permission denial.
• Test microphone permission denial during voice recording.
• Test background-location preferences where applicable.
• Test battery-optimization accepted, declined, and unavailable paths.
• Test configuration changes during onboarding.
• Test onboarding restoration after process recreation.

Android-version matrix

• Define minimum, target, and newest-supported API test matrix.
• Add emulator coverage for behavior changes in permissions and foreground services.
• Add at least one low-memory/process-death scenario.
• Add manufacturer-device coverage for known BLE/background differences.

Acceptance criteria

• Critical service and permission flows have Robolectric or instrumented coverage.
• No permission denial crashes or leaves onboarding irrecoverable.
• Service recreation does not duplicate transports or lose required state.
• Required API-level matrix passes before release.

---

Milestone 8: Persistence, migration, and recovery testing

Status: Not started
Progress: 0%

Goal

Ensure identities, settings, aliases, favorites, bookmarks, messages, and capability pins survive upgrades and fail safely when storage is incomplete or corrupt.

TODO checklist

• Inventory every persisted key, file, schema, and version marker.
• Create legacy fixtures for every supported application version.
• Test clean first launch with no persisted state.
• Test upgrade from each retained legacy fixture.
• Test unknown future fields are preserved or ignored safely.
• Test truncated, malformed, empty, and type-mismatched preference values.
• Test partial multi-key identity writes.
• Test storage write failure and rollback.
• Test concurrent readers and writers.
• Test alias merging and canonical conversation migration.
• Test chronological ordering after migration.
• Test favorite and bookmark preservation.
• Test message-retention expiry with fake time.
• Test secure identity clearing removes all linked mappings and pins.
• Test signing-key and capability rotation is atomic.
• Test backup/restore policy does not duplicate or expose sensitive identity material.
• Test migration idempotence by running each migration twice.
• Test downgrade behavior when a newer schema has already been written.

Acceptance criteria

• Every supported legacy fixture migrates deterministically.
• Failed migrations leave either the old valid state or the new valid state, never a partial mixture.
• Security-sensitive corruption fails closed with a recoverable user path.
• Migration and retention behavior uses deterministic storage and time.

---

Milestone 9: UI, media, and accessibility testing

Status: Not started
Progress: 0%

Goal

Protect user-visible behavior and media workflows while keeping most assertions at ViewModel/state boundaries and reserving Compose instrumentation for genuine interaction and rendering contracts.

TODO checklist

ViewModels and application state

• Restore or replace the currently skipped command-processor tests.
• Restore or replace the currently skipped notification tests.
• Test public/private/channel conversation switching.
• Test optimistic send, success, failure, retry, and cancellation.
• Test delivery and read-receipt transitions.
• Test peer arrival, departure, alias change, and identity rotation.
• Test state restoration after configuration change and process recreation.
• Test concurrent inbound messages while changing conversations.
• Test error messages for permission, transport, storage, and crypto failures.

Compose UI

• Add semantics tests for critical chat actions.
• Test onboarding navigation and recoverability.
• Test empty, loading, connected, disconnected, and error states.
• Test long nicknames, messages, channels, and localized text.
• Test dynamic font sizes and display scaling.
• Test light, dark, and supported theme variants.
• Add screenshot tests only for stable high-value layouts.
• Test keyboard, focus, back navigation, and bottom-sheet behavior.
• Test screen-reader labels, traversal order, and minimum touch targets.
• Test reduced-motion behavior where animations are nonessential.

Files, images, and voice

• Test zero-byte, small, maximum-size, and oversized files.
• Test unsupported and misleading MIME types.
• Test missing filenames and Unicode filenames.
• Test file read/write failures and insufficient storage.
• Test image decode failures, orientation metadata, and large-image memory limits.
• Test voice-recording start, pause/stop, cancellation, and microphone loss.
• Test corrupt and unsupported audio playback.
• Test waveform generation boundaries.
• Test interrupted private-media preparation and commit rollback.
• Test cleanup of temporary files after success, failure, and cancellation.

Acceptance criteria

• Critical user journeys pass through state-level tests.
• A focused Compose suite protects navigation, semantics, and accessibility.
• Media failures are visible, recoverable, and leak no temporary resources.
• Previously skipped UI-related tests are either active or replaced with equivalent coverage.

---

Milestone 10: Physical-device and cross-client release gate

Status: Not started
Progress: 0%

Goal

Validate the behavior that JVM, Robolectric, and emulator tests cannot prove: real radios, background limits, device interoperability, and compatibility with released clients.

TODO checklist

Device matrix and harness

• Define a minimum physical-device matrix covering at least two Android API levels and two manufacturers.
• Include devices supporting BLE only and BLE plus Wi-Fi Aware where available.
• Build a test control channel that does not interfere with mesh transport.
• Capture structured traces, packet IDs, connection transitions, and failure reasons.
• Make test accounts, identities, and files disposable and non-personal.
• Provide deterministic scenario setup and cleanup.

Android-to-Android scenarios

• Discover, connect, exchange announcements, disconnect, and reconnect.
• Send public and private messages in both directions.
• Verify delivery and read receipts.
• Transfer image, audio, and generic files at multiple sizes.
• Relay across at least three devices.
• Partition the mesh and verify store-and-forward delivery after reconnect.
• Disable and re-enable Bluetooth during active transfers.
• Lock screens and background both apps during active mesh operation.
• Kill and recreate one process.
• Exercise simultaneous connections and duplicate-link resolution.
• Exercise Wi-Fi Aware failover where supported.

Cross-client and backward compatibility

• Test current Android against the current iOS client.
• Test the rewrite against the last supported Android release.
• Test legacy announcements without capabilities.
• Test current capability announcements with an older client.
• Test canonical private-media type and decode-only prerelease alias.
• Compare packet, message, identity, fragment, sync, and file golden vectors across implementations.
• Verify malformed and unauthenticated inputs are rejected consistently.
• Verify Nostr fallback messages and receipts across clients.

Background and endurance

• Run a multi-hour discovery/connect/disconnect soak test.
• Run repeated large-transfer and cancellation cycles.
• Monitor memory, threads, file descriptors, wake locks, and battery impact.
• Test foreground-service survival with screens off.
• Test network and Tor availability changes during Nostr operation.
• Confirm shutdown releases radios, sockets, jobs, and wake locks.

Acceptance criteria

• All mandatory scenarios pass on the defined device matrix.
• Android/iOS and old/new clients exchange every supported critical payload.
• No endurance run shows unbounded growth or leaked resources.
• Failures produce sufficient traces for deterministic reproduction where possible.
• Release approval records the client versions, device matrix, and results.

---

CI rollout

Pull-request gate

• Run formatting and static analysis.
• Run deterministic JVM unit tests.
• Run bounded property/fuzz tests.
• Run stable Robolectric tests.
• Run clientRewriteContractTest.
• Upload JUnit and coverage reports.
• Reject new failures, errors, or unexpected skips.
• Reject golden-vector changes without the protocol-change review label.

Main and nightly gate

• Run the extended fuzz corpus.
• Run emulator instrumented tests.
• Run local relay/Tor integration tests.
• Run physical-device smoke tests when the lab is available.
• Track runtime, flakes, coverage, and quarantined tests.

Release-candidate gate

• Run the complete device matrix.
• Run Android/iOS and old/new interoperability.
• Run endurance and background scenarios.
• Review all skipped or quarantined tests.
• Archive coverage, test, trace, and version metadata with the release.

Progress update procedure

When work lands:

1. Check completed TODOs in the relevant milestone.
2. Update the milestone percentage based on completed checklist items.
3. Change status to In progress when its first TODO is complete.
4. Change status to Complete only when all acceptance criteria are met.
5. Update the top-level progress table and milestone completion count.
6. Link the implementing pull request or commit next to material completed work without including personal information.
7. Record intentionally deferred items and their justification; do not mark them complete.

Final definition of done

The test program is complete when:

• Milestones 0–10 meet every acceptance criterion.
• Project and package-level line/branch coverage no longer regress.
• All critical parsers have adversarial and fuzz coverage.
• All security-sensitive state transitions fail closed under tampering, replay, downgrade, and corruption.
• Transport, sync, and lifecycle tests cover disconnection, cancellation, timeout, and restart.
• Physical-device and cross-client scenarios pass for every release.
• The full rewrite can replace the existing implementation while preserving the unchanged compatibility and acceptance tests.